[[chapter_mailfilter]] Rule-Based Mail Filter ====================== {pmg} ships with a highly configurable mail filter. It’s an easy but powerful way to define filter rules by user, domains, time frame, content type and resulting action. [thumbnail="pmg-gui-mail-filter-rules.png", big=1] Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT' and 'ACTION'), and each category may contain several objects to match certain criteria: 'Who' - objects:: Who is the sender or receiver of the e-mail? Those objects can be used for the 'TO' and/or 'FROM' category. + ==== Example: EMail-object - Who is the sender or receiver of the e-mail? ==== 'What' - objects:: What is in the e-mail? + ==== Example: Does the e-mail contain spam? ==== 'When' - objects:: When is the e-mail received by {pmg}? + ==== Example: Office Hours - Mail is received between 8:00 and 16:00. ==== 'Action' - objects:: Defines the final actions. + ==== Example: Mark e-mail with “SPAM:” in the subject. ==== Rules are ordered by priority, so rules with higher priority are executed first. It is also possible to set a processing direction: 'In':: Rule applies for all incoming e-mails 'Out':: Rule applies for all outgoing e-mails 'In & Out':: Rule applies for both directions And you can also disable a rule completely, which is mostly useful for testing and debugging. The 'Factory Defaults' button alows you to reset the filter rules. [[pmg_mailfilter_action]] 'Action' - objects ------------------ [thumbnail="pmg-gui-mail-filter-actions.png", big=1] Please note that some actions stops further rule precessing. We call such actions 'final'. Accept ~~~~~~ Accept mail for Delivery. This is a 'final' action. Block ~~~~~ Block mail. This is a 'final' action. Quarantine ~~~~~~~~~~ Move to quarantine (virus mails are moved to the “virus quarantine”, other mails are moved to “spam quarantine”). This is also a 'final' action. Notification ~~~~~~~~~~~~ Send notifications. Please note that object configuration can use xref:rule_system_macros[macros], so it is easy to include additional information. For example, the default 'Notify Admin' object sends the following information: .Sample notification action body: ---- Proxmox Notification: Sender: __SENDER__ Receiver: __RECEIVERS__ Targets: __TARGETS__ Subject: __SUBJECT__ Matching Rule: __RULE__ __RULE_INFO__ __VIRUS_INFO__ __SPAM_INFO__ ---- Notification can also include a copy of the original mail. Blind Carbon Copy (BCC) ~~~~~~~~~~~~~~~~~~~~~~~ The BCC object simply sends a copy to another target. It is possible to send the original unmodified mail, or the processed result. Please note that this can be quite different, i.e. when a previous rule removed attachments. Header Attributes ~~~~~~~~~~~~~~~~~ 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. .'Modify Spam Level' Header Attribute ---- Field: X-SPAM-LEVEL Value: __SPAM_INFO__ ---- Another prominent example is the 'Modify Spam Subject' action. This simply adds the 'SPAM:' prefix to the original mail subject: .'Modify Spam Subject' Header Attribute ---- Field: subject Value: SPAM: __SUBJECT__ ---- Remove attachments ~~~~~~~~~~~~~~~~~~ Remove attachments can either remove all attachments, or only those matched by the rules 'What' - object. You can also specify the replacement text if you want. You can optionally move those mails into the attachment quarantine, where the original mail with all attachments will be stored. The mail with the attachments removed will continue in the rule system. NOTE: The Attachment Quarantine Lifetime is the same as for the Spam Quarantine. Disclaimer ~~~~~~~~~~ Add a Disclaimer. [[pmg_mailfilter_who]] 'Who' - objects --------------- [thumbnail="pmg-gui-mail-filter-who-objects.png", big=1] This type of objects can be used for the 'TO' and/or 'FROM' category, and macth the sender or receiver of the e-mail. A single object can combine multiple items, and the following item types are available: EMail:: Allows you to match a single mail address. Domain:: Only match the domain part of the mail address. Regular Expression:: This one uses a regular expression to match the whole mail address. IP Address or Network:: This can be used to match the senders IP address. LDAP User or Group:: Test if the mail address belong to a specific LDAP user or group. We have two important 'Who' - objects called 'Blacklist' and 'Whitelist'. Those are used in the default ruleset to globally block or allow specific senders. [[pmg_mailfilter_what]] 'What' - objects ---------------- [thumbnail="pmg-gui-mail-filter-what-objects.png", big=1] 'What' - objects are used to classify the mail content. A single object can combine multiple items, and the following item types are available: Spam Filter:: Matches if detected spam level is equal or greater than the configured value. Virus Filter:: Matches on infected mails. Match Field:: Match specified mail header fields (eg. `Subject:`, `From:`, ...) Content Type Filter:: Can be used to match specific content types. Match Filename:: Uses regular expressions to match attachment filenames. Archive Filter:: Can be used to match specific content types inside archives. [[pmg_mailfilter_when]] 'When' - objects ---------------- [thumbnail="pmg-gui-mail-filter-when-objects.png", big=1] 'When' - objects are use to activate rules at specific daytimes. You can compose them of one or more time-frame items. The default ruleset defines 'Office Hours', but this is not used by the default rules. [[pmg_mailfilter_regex]] Using regular expressions ------------------------- A regular expression is a string of characters which tells us which string you are looking for. The following is a short introduction in the syntax of regular expressions used by some objects. If you are familiar with Perl, you already know the syntax. Simple regular expressions ~~~~~~~~~~~~~~~~~~~~~~~~~~ In its simplest form, a regular expression is just a word or phrase to search for. `Mail` would match the string "Mail". The search is case sensitive so "MAIL", "Mail", "mail" would not be matched. Metacharacters ~~~~~~~~~~~~~~ Some characters have a special meaning. These characters are called metacharacters. The Period (`.`) is a commonly used metacharacter. It matches exactly one character, regardless of what the character is. `e.mail` would match either "e-mail" or "e-mail" or "e2mail" but not "e-some-mail". The question mark (`?`) indicates that the character immediately preceding it either zero or one time. `e?mail` would match either "email" or "mail" but not "e-mail". Another metacharacter is the star (`*`). This indicates that the character immediately to its left may repeated any number of times, including zero. `e*mail` would match either "email" or "mail" or "eeemail". The plus (`+`) metacharacter does the same as the star (*) excluding zero. So `e+mail` does not match "mail". Metacharacters may be combined. A common combination includes the period and star metacharacters (`.*`), with the star immediately following the period. This is used to match an arbitrary string of any length, including the null string. For example: `.*company.*` matches "company@domain.com" or "company@domain.co.uk" or "department.company@domain.com". The book xref:Friedl97[] provides a more comprehensive introduction.