cPanel Addon

This topic describes how to integrate the cPanel spam filter addon.

cPanel Server Recommended Setup

The following steps describe how to set up optimal protection for the cPanel server:

  1. Log into the Super-Admin Level Control Panel
  2. Select Users & Permissions > Manage Admins and select Add to create a new admin account for the cPanel server in Spam Experts
  3. Install the Spam Experts cPanel addon. This can be done via the command line using the following command:

    4. wget -N https://download.seinternal.com/integration/installers/cpanel/installer.sh && bash installer.sh

  4. For new versions, if required, select Remote Access Key (now available, after the previous step) and click Generate New Key

  5. Configure the correct API/MX/user details for the cPanel addon

  6. Disable incoming filters from the Spam Experts servers

    1. For Local Cloud, select Exim Configuration Manager > Basic Editor > Access Lists > Only-Verify-Recipient
    2. For Hosted Cloud, ensure proper delivery from the filtering servers
  7. Run bulk protect from the addon in WHM
  8. Restart Bind:

    /etc/init.d/named restart

  9. For outgoing filtering: Set outgoing smarthost details

A re-run of the installer will not overwrite the addon configuration.

System Requirements

To use the cPanel addon, ensure your system is configured according to the following requirements:

  • Full root/shell access to be able to install the addon
  • cPanel running from stable/release/current versions only (we cannot support edge). LTS versions are not supported
  • The Spam Experts Local Cloud or Hosted Cloud product and admin credentials
  • The "Change MX" feature has to be enabled in the feature list. To do this, select Packages > Feature Manager, click on Edit Feature List and tick the MX entry box. This should be enabled by default
  • PHP 5.4 or above
  • PHP support for:
    • cURL
    • OpenSSL (recommended, not mandatory)

Addon: cPanel

The cPanel part of the addon provides the end user with a (brandable) icon in their control panel, allowing them to view and log into their domains.

The List Accounts section displays a list of domains for which the Cpanel Addon has been installed.

Click the Cpanel orange icon next to each domain, this will automatically log you into the spam filter, where you can manage all antispam settings for the domain.

Addon: WHM

The WHM part of the addon includes all configuration options and features for the Super-admin user. To access this menu, search for Plugins in the WHM interface > Professional Spam Filter.

Click the icon to open the addon's main menu.

Configuration

The Configuration panel allows you to configure all the necessary settings for the addon. Generally, the default settings are sufficient but can be customised to suit your needs.

On mouseover, a tooltip with the option description is displayed.

To use the addon on the Hosted Cloud there are some additional steps required. See Integrations and Addons.

For a detailed overview of the Configuration options, see the Configuration Details section (below).

Branding

Using the branding option, you can change the appearance of the cPanel icon to match your own branding. This functionality is only available if you have purchased the Private Label (White label) or Premium Private Label (Premium white label).

Domain List

The domain list shows you all the local domains and allows you to check if it is protected and exists in the Spam Filter. You can also choose to log in to it.

Clicking Check Status or Check all domains displays if the domain is added to the filter.

Using Toggle Protection, you can either add or remove the domain from the Spam Experts Control Panel.

Bulkprotect

The Bulkprotect option allows you to protect all domains on the local system.

Clicking Enable bulkprotect enables the bulk protect system. This may take some time as it has to iterate through all domains (account, addon, parked) and execute all the various tasks involved in protecting the domain (for example: adding it, changing MX records, setting email address for reports).

On servers with a lot of domains (1000+) using the User Interface for running bulk protection can be too resource-intensive. To handle large domain lists better, the addon provides a command-line utility for running the bulk-protection procedure. It can only be executed in root sessions by running the following commands:

cd /usr/local/prospamfilter

php bin/bulkprotect.php

Migration

The migration page allows you change the username and re-assign all domains to that user. For example, if the destination user is an admin:

The migration process requires that you enter the new user's username and password, to verify you have access to that account. During the migration, the domains will be assigned to this new user.

Once the process is complete, the username and password is updated for the addon configuration.

We strongly recommend each cPanel server to use it's own Control Panel API credentials. Whenever you move an account from one cPanel server to another, you should first transfer the ownership of the domain from the old web interface user to the new one. That way, the old cPanel server does not have access to the domain anymore (and won't delete it), whilst the new server does have access (allowing the client to log in).

Update

In the Update page you can enable auto-update or manually update the version to the latest one. You can also choose what type of updates you'd like to receive: manually updating or reinstalling the current version.

We highly recommend you use the tested and preferred, stable builds at all times.

The testing and trunk builds are updated more often but may contain bugs.

Support

The support page contains basic information about which versions are being used and generates a special code.

The special code contains a collection of data which can help troubleshoot any problems. Please provide this information when contacting Support with related queries.

Configuration Details

SpamPanel URL

What URL is being used to manage the Spamfilter? This can be the primary hostname of your cluster or a CNAME that you are using.

If you want to use https://, you must configure SSL support for cpsrvd.

This URL will be validated. If it is not a Control Panel URL, you will be informed.

API hostname

The hostname is being used to interface with the API. This is the hostname of your primary server.

API username

The API username should be a sub-admin or admin account. We recommend that you use a separate sub-admin user for each cPanel server. For security reasons, we advise against using Super Admin credentials. Also, ensure that you do not use a “Software API” user.

API password

The API password is the one that belongs to the API user. The combination of hostname, username, password and SSL enabled/disabled is validated. If the login fails, you will be notified so you can make the appropriate adjustments.

Primary MX

The Primary MX record (MX10).

Secondary MX

The optional Secondary MX record (MX20).

Tertiary MX

The optional Tertiary MX record (MX30).

TTL to use for MX records

You can select which TTL the addon should use when creating MX records for the domain it is protecting.

Enable SSL for API requests

Use SSL for API requests. Please note that this will require cpsrvd to be compiled with OpenSSL. This checkbox will be unchecked/greyed out when your PHP version/server does not support OpenSSL.

Enable automatic updates

Updates are being performed once a week to make sure the addon is running the most recent version. If you tick this box, the addon will periodically check if updates are available. If there is an update, it will be installed automatically.

You can also update manually through the addon's “Update” feature.

Automatically add domains to the SpamFilter

Tick this box if you want the addon to create new domains in the Spam Experts Control Panel when it is being added to cPanel.

Automatically delete domains from the SpamFilter

Tick this box if you want the addon to remove domains from the SpamFilter when they are being removed from cPanel.

Automatically change the MX records for domains

Tick this box if you want the addon to change the MX records for your domains. This option uses the Primary/Secondary/Tertiary MX records to provision the DNS for a new domain, or when you are executing Bulk Protect.

Configure the email address for this domain

Automatically sets the contact address for the domain in the Spam Filter. Using this, customers can leverage the "Retrieve login link" feature if they forget their password and will start receiving Protection Reports for their domain. For protection reports, the default settings are used.

This function will work only if your account has an email address attached in cPanel.

Process addon- and parked domains

Tick this box if you want the addon to handle addon and parked domains.

Add addon- and parked domains as an alias instead of a normal domain.

If this box is unticked, and the previous one ticked, domains will be added as normal standalone domains. That is the recommended value. If you tick this box (and the previous one is ticked), addon- and parked domains will be added as special domain aliases for the root domain. We strongly recommend that you de-select this feature, as addon/parked domains may have different mail rules set up and, as a result, email may malfunction as the account does not exist on the main domain.

Use existing MX records as routes in the SpamFilter.

If you tick this box, instead of the server hostname, the original MX records for that domain will be used as destination hosts. You can use this for specific server setups, such as Google Apps.

Do not protect remote domains

If selected, this will skip protecting domains that are set to “remote”.

By enabling this option and the “use existing MX records as routes in the SpamFilter” option, you can protect the domain transparently. The existing MX records are used which point to the remote server which the Spamfilter delivers mail to.

Redirect back to controlpanel upon logout

Tick this box if you want the user to be redirected back to cPanel when they click the logout button in the Spam Experts interface.

Add the domain to the SpamFilter during login if it does not exist

This option adds the domain to the filter if the domain does not already exist at login. This is useful to auto-protect domains that are not yet protected at login.

Force changing route & MX records, even if the domain exists.

If selected, this changes the route to this server and MX records in case the domain already exists. This feature is useful when you are frequently migrating domains between multiple cPanel boxes.

Change email routing setting "auto" to "local" in bulk protect.

The “email routing” setting can be set to “local” (this server handles email) in case the domain is set to “auto”. Auto is a dangerous setting that may lead to issues in the email delivery. By ticking this box, domains set to “auto” will be changed into “local”.

Add/Remove a domain when the email routing is changed in cPanel

When the email routing is being changed in the “Edit MX records” setting, you can have the addon automatically remove the domain if it is set to anything but local or add the domain if it is switched to local.

IP as Destination route instead of domain

With this turned on all newly added domains should have destinations represented with IP addresses. With the option turned off the destinations should be hostnames.

Configuring PHP to support cURL and OpenSSL

The addon relies on cURL to communicate with the API's it uses. You'll need to ensure both cURL and OpenSSL are supported via EasyApache. The activate this, login as super-administrator to WHM:

  1. Select EasyApache (Apache Update)
  2. Choose Start customizing based on profile
  3. Follow the steps, until the Exhaustive Options List is displayed
  4. Select OpenSSL and CurlSSL, click Save and build

Configuring PHP with EasyApache4

EasyApache 4's packages for PHP modules and extensions use the ea-php##-php-module naming convention, where ## represents the PHP version number and module represents the name of the PHP module.

Install a PHP module or extension on your system with one of the following methods:

  • Use WHM's EasyApache 4 interface (Home > Software > EasyApache 4)
  • Install the package on the command line with the following command:

    yum install ea-php56-php-gd

The above example installs the ea-php56-php-gd package, where 56 represents the PHP version and gd represents the extension name.

cPanel v54 X3 Theme

cPanel v54 has introduced some changes to the X3 theme which they have officially deprecated and plan to remove by the end of 2016. Unfortunately this can cause an issue with our plugin's icon for that particular theme, which might no longer be displayed properly.

More details about X3 theme deprecation and scheduled removal can be found in cPanel's blog post.

We would strongly advise our customers to no longer use the X3 theme starting with v54 and switch to the new default one that cPanel recommends instead, for which they've also added a 'Retro' styling option to make it look like X3.

However, if anyone still wants to use X3 theme on v54 for any reason and has an issue with our plugin's icon not being displayed properly, the following cPanel script can be used to fix the issue: '/usr/local/cpanel/bin/rebuild_sprites`.

Troubleshooting

There are two parts of enabling debug mode, one is enabling debug mode for the addon and the other is to have syslog save debug-level logs. Both steps are required to successfully enable debug level logging.

You can enable the addon's debug mode by entering the following in a terminal:

touch /etc/prospamfilter/debug

This feature should only be enabled when there is a problem and you want to debug it.

To disable it, enter:

rm /etc/prospamfilter/debug

We recommend to enable debugging when there are problems (white pages, unexplainable errors). This mode logs quite some information to the log file and starts displaying more errors in the Control Panel.

Log Debug Level Data

This is very important in the event of any issues you may encounter with your installation. Please follow the below steps to log debug level data:

First, you must change your syslog settings.

cPanel (or CentOS) has a default setup which ignores the "DEBUG" entries.

To make them show up, you can add the following line to /etc/syslog.conf (or /etc/rsyslog.conf) and restart (r)syslog afterwards:

*.debug                              /var/log/debug

To restart syslog or rsyslog, depending on the case, just execute one of the following commands:

sudo service syslog restart

sudo service rsyslog restart

If you want to keep this enabled for a longer period, you might want to add it to the log rotation configuration.

The log will be stored on /var/log/debug.

Upgrade Instructions

The system automatically updates itself (when enabled), and can optionally be updated manually via the web interface. If you experience any issues using the web-based/automatic updater, please contact our support. You can always run the installation command as above to force a new install of the latest version of the addon, all settings will remain preserved.

Uninstall Instructions

In case you want to remove the addon, you have to run the uninstaller using the following command:

cd /usr/local/prospamfilter/bin/ && ./uninstall.php

The above command will just uninstall the addon, but all added domains will still be protected as mail will be routed through the Spam Experts system and the MX Records will still point to your Local or Hosted Cloud solution.

To remove all domains from the Spam Experts system and reset the MX Records to their original state from before the addon’s installation, run the following command:

cd /usr/local/prospamfilter/bin/ && ./uninstall.php --resetmx

Downgrade Instructions

  1. If you need to downgrade to an unsupported version, (for example when a WHM version becomes LTS or EOL), you need to use the following instructions. Please note that support for a older version is not supported. This should only be used in emergencies. It is strongly recommended to upgrade your WHM platform to a supported version

    2. Execute the following

    wget https://raw.githubusercontent.com/spamexperts/cpanel-addon/master/bin/installer/old_installer.sh
    chmod +x old_installer.sh
    ./old_installer.sh x.x.xxxxx

    Replacing x.x.xxxxx with the addon version number you wish to downgrade too

  2. Disable the "automatic updates" from the addon settings page