bump version to 5.0-8

[pmg-docs.git] / pmg-mail-filter.adoc

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[]

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.


'Action' - objects
------------------

image::images/screenshot/pmg-gui-mail-filter-actions.png[]

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.


Disclaimer
~~~~~~~~~~

Add a Disclaimer.


'Who' - objects
---------------

image::images/screenshot/pmg-gui-mail-filter-who-objects.png[]

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.


'What' - objects
----------------

image::images/screenshot/pmg-gui-mail-filter-what-objects.png[]

'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 configured value if greater than the detected spam level.

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.


'When' - objects
----------------

image::images/screenshot/pmg-gui-mail-filter-when-objects.png[]

'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.


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.