-Mail Filter
-===========
+[[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.
-image::images/screenshot/pmg-gui-mail-filter-rules.png[]
+[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' - 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' - objects::
What is in the e-mail?
+
Example: Does the e-mail contain spam?
====
-WHEN - objects::
+'When' - objects::
When is the e-mail received by {pmg}?
+
Example: Office Hours - Mail is received between 8:00 and 16:00.
====
-ACTIONS - objects::
+'Action' - objects::
Defines the final actions.
+
reset the filter rules.
-Actions
--------
+[[pmg_mailfilter_action]]
+'Action' - objects
+------------------
-image::images/screenshot/pmg-gui-mail-filter-actions.png[]
+[thumbnail="pmg-gui-mail-filter-actions.png", big=1]
Please note that some actions stops further rule precessing. We call
such actions 'final'.
~~~~~~~~~~~~~~~~~~
Remove attachments can either remove all attachments, or only those
-matched by the rules 'WHAT' object. You can also specify the
+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.
+This also matches the content-types of all regular (non-archived) attachments.
+
+Match Archive Filename::
+
+Uses regular expressions to match attachment filenames inside archives.
+This also matches the filenames for all regular (non-archived) attachments.
+
+
+[[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.
\ No newline at end of file
projects / pmg-docs.git / blobdiff