Hidden Features - MailCleaner/MailCleaner8 GitHub Wiki
MailCleaner is a very open platform. It provides full access to essentially all of the source code and configuration files. This is a very good thing, because it allows admins the flexibility to apply their own changes and configurations beyond what is possible in the Administrator Interface. However, you need to do so with extreme caution. Changes to the source code or system components can easily break expected behavior or block the Git repository from updating.
Below are some hacks that can be done without too much risk, and in some cases, we have even added shortcuts to make them easier and safer. However, these are still generally risky of advanced options that we discourage you from using unless you have no other choice. Use any of them at your own risk and expect us not to be able to provide support in the event that these do cause problems.
Full Whitelist
The full whitelist feature allows mails to bypass all forms of filtering. Unlike other whitelists, this includes all filters in the SMTP phase, virus filtering and content protection policies.
Configuration
Mails will be fully whitelisted if it meets 2 criteria:
- The sending mail server host has to be in the file
/var/mailcleaner/spool/mailcleaner/full_whitelisted_hosts.list
Shorthands and CIDR notation are allowed according to the same conditions as other hostlist boxes as discussed here
- The sending mail address has to be in the file
/var/mailcleaner/spool/mailcleaner/full_whitelisted_senders.list
Wildcard addresses can be allowed with '*'. For example you can whitelist a domain with *@domain.com. This uses Exim address list formatting which is simplest to implement one-per-line in a file context.
Legacy Support
Until recently a beta version of this feature used this pre-existing field for the host list Configuration->AntiSpam->Trusted IPs/Networks.
This configuration is still supported if the 'full_whitelisted_hosts.list' file does not exist. It is recommended that you migrate to the dedicated file if you have been using the "Trusted IPs/Networks" field.
This legacy method is discouraged because adding the hosts to that field necessarily means that all other mail from those hosts will skip basic spam filtering also. For example, if you add Office365 to the host list so that you can fully whitelist a single address who use that service, you would also be skipping SpamC, PreRBL, UriRBL, etc. for all other email originating from those IPs. Using the dedicated file does not result in this problem.
Technical details
This feature functions by being the highest priority router in the Incoming MTA configuration. The top priority ensures that all SMTP access controls are not evaluated. Instead of forwarding to the Filtering MTA, this router will forward directly to the Outgoing MTA meaning that there won't even be an opportunity for the messages to be flagged. This is unlike regular whitelists which will still hit the Filtering MTA, but which ignore the spam flag if detected.
More Frequent Summary Reports
MailCleaner sends summaries about the mail caught in spam filters per day, week or month.
If you want to get it more often within any of those cycles, this is doable but there are STRONG downsides since the code sending these summaries was not meant to be use that way.
To avoid getting those downsides, we recommend just using the Tag mode of MailCleaner. The mail server or user's mail reader should be able to be configured to direct messages with the Subject tag directly to a Junk folder. This will allow for immediate access to the messages, without having them clog up the Inbox or getting confused with legitimate messages.
If necessary, an admin could schedule additional reports, since this the existing reports are simply a child process of the regular cron task anyways. For this example, let us say you want your user to get the summaries every 2 hours during the workday and that your existing daily tasks run at 09:00. This can be done by supplementing for the remaining instances with another cron task. Edit the crontab file with:
crontab -e
Then create a new task like:
0 11,13,15,17 * * * /usr/mailcleaner/bin/send_summary.pl [email protected] 3 0
In this example [email protected] is the user who will be getting the additional reports, the 3 indicates the frequency type (0 = one-time commandline usage; 1 = monthly; 2 = weekly; 3 = daily) and 0 indicates the number of preceding days to include (0 means "since the start of yesterday"). The rest is standard cron formatting and you can see the cron documentation for more.
The crontab should only be modified on the master server of a cluster. In the above example, you can set a mail address like [email protected], a whole domain like mailcleaner.net or -a if this would have to be done for all users of all domains.
As noted briefly, the reports include incidents since the start of the day, for as many days back as you define. So, this means that multiple reports per day can be tedious since the copy sent at 17:00 will contain all of the same entries as 15:00, plus any received in the last 2 hours. Even if there was nothing caught in the last 2 hours, MailCleaner does not keep track of previous reports, so it will send the identical notification again.
Modifying Exim configuration templates
It is possible to make modifications to the Exim template files so that the generated configuration files contain your own custom settings. We strongly discourage this, since modifications can potentially block updates.
Note that the configuration templates are versioned based on the currently installed Exim release. Below, we will use the suffix _4.98 which is the release available at the time of writing, but you will need to verify that this is correct for your installation. If you have modifications to your templates, updates to later versions will be blocked, as discussed here
Exim Stage 1 (Incoming MTA)
This is the most sophisticated template, which does most of the filtering which is configured in Configuration->SMTP, the initial Configuration->Domains->[select domain]->Recipient verification and many other checks. It eventually passes acceptable mail to Stage 2. Outgoing messages are delivered directly by Stage 1 without passing through the other MTA stages.
It uses the configuration template /usr/mailcleaner/etc/exim/exim_stage1.conf_template_4.98.
Exim Stage 2 (Filtering MTA)
This is the most simplistic template. It essentially just listens to accept forwarded messages from Exim Stage 1 and then saves them to a directory where they will be filtered by MailScanner.
It uses the configuration template /usr/mailcleaner/etc/exim/exim_stage2.conf_template_4.98.
Exim Stage 4 (Outgoing MTA)
This template handles final delivery of all incoming emails. After MailScanner finishes scanning the message which were queue by Stage 2, it provides the results to the SpamHandler module. SpamHandler decides whether to place the message in a quarantine, drop it or to place it in the queue for this stage. This MTA will handle find the proper delivery location, perform DKIM signing and queue the messages for later delivery if necessary. It also handles the Copy-To and Archiving steps.
It uses the configuration template /usr/mailcleaner/etc/exim/exim_stage4.conf_template_4.98.
Included files
The templates have various __INCLUDE__ and .include_if_exists statements which will insert additional code from other files. For example:
__INCLUDE__ stage1/ldap
This will insert, unmodified, the contents of /usr/mailcleaner/etc/exim/stage1/ldap at that location. This file is likewise also generated from a template named /usr/mailcleaner/etc/exim/custom/stage1/ldap_template_4.98.
If there is no versioned template file, it will look for an unversioned one, ie. /usr/mailcleaner/etc/exim/custom/stage1/ldap_template.
The dumper script does a "glob" search for all additional '*_template' files, so you can potentially split your configuration into a separate file, add an __INCLUDE__ to the base template and then have the dumper substitute any existing __VARIABLES__.