How to manage custom, server-wide Exim filters in cPanel, and how to quickly enable and disable them in the WHM UI

Introduction

This guide explains the cPanel specific steps for managing custom server wide filters for Exim.

This guide provides an example with basic logging, new header addition, and basic conditional syntax, but cPanel support is not able to provide support for the details of crafting custom filters to fit your specific needs. Please reach out to a systems administrator or review the documentation for those questions.

Before getting into the specifics of managing custom filters this introduction will also cover some basic concepts to help you understand if a custom Exim filter is the right solution for your situation. Please see the "Procedure" section below for cPanel specifics of managing filters.

What is an Exim Filter?

An Exim filter is a configuration file that allows a systems administrator to check and manipulate email messages as they pass through the server. Where ACLs allow for the systems administrator to do this before the message has been accepted, filters allow for this after the message has been accepted, but before the message is either delivered locally or sent to a remote mail server for further processing. Filters apply to both incoming and outgoing messages. If you need to operate on a message before the server accepts the message, you should research the use of Exim ACLs instead.

What can Exim Filters do?

Exim filters are commonly used to redirect and forward messages, however they're also capable of:

- Logging most any information that you can think of about a message that is processed by the filter

- Adding, Removing, and Editing headers

- Providing logical constructs such as if statements that allow for complex processing

- Piping messages to external scripts for processing

- More

Please see the Exim documentation for a more in depth understanding of what Filters are and what they are capable of:

Exim Documentation: Chapter 3 - Exim Filter Files

Exim Documentation: Chapter 47 - System-Wide Message Filtering

Procedure

To Create a New Custom Filter

1. Login to the server via SSH or Terminal as the root user
2. Create a new file under the /usr/local/cpanel/etc/exim/sysfilter/options directory. Keep in mind that the name of the file you create will be used in the WHM UI in later steps, so it is important to choose a filename that accurately represents what the filter should accomplish.
   The example filter here will create a special log for all instances of messages that are over 3MB in size so the name will be log_large_messages:

   touch /usr/local/cpanel/etc/exim/sysfilter/options/log_large_messages

3. Open the newly created file with the text editor of your choice and add the following contents:

   if $message_size is above 3m
   then
   add_header = X-Large-Message: This message is over 3MB
   logfile /var/log/exim_large_messages.log
   logwrite "$tod_full $message_id This message is larger than 3MB"
   finish
   endif

4. In this case since the filter will do logging we must create the log file and set the correct ownership. If you are adding logging to a filter and you fail to properly create the log file, Exim will fail to start.

   touch /var/log/exim_large_messages.log
   chown cpaneleximfilter:cpaneleximfilter /var/log/exim_large_messages.log

5. Now that the filter and log are in place you can enable the new filter via WHM. Login to WHM as the root user.
6. Navigate to: Home »Service Configuration »Exim Configuration Manager
7. Click on the grey "Filters" tab in the Exim Configuration Manager
8. Scroll to the bottom where you will see an option with a yellow Exclamation point icon that is labeled:

   Custom Filter: log_large_messages

   The yellow exclamation point indicates that a new option has been enabled, but Exim has not yet been restarted so the change is not yet in effect.
9. If you want to enable the filter right away, leave the option set to "On" for this filter
10. If you do not want to enable it just yet, set the option for this filter to "Off"
11. Click the blue Save button to rebuild the Exim configuration to include this new filter and restart Exim to read the newly built configuration.
    CAUTION: If there is a syntax or other problem with your new filter, Exim may fail to start properly. Pay close attention to the output provided on the next screen for any possible error messages.

To Enable or Disable an Existing Custom Filter

1. Login to WHM as the root user
2. Navigate to: Home »Service Configuration »Exim Configuration Manager
3. Click on the grey "Filters" tab in the Exim Configuration Manager
4. Scroll to the bottom and look for the custom filter of interest
5. Set the option for that filter to either On or Off
6. Click the blue save button to rebuild the Exim configuration and restart