cPanel Addon

cPanel Server Recommended Setup

Set up optimal protection for the cPanel server:

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

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

  5. Select Remote Access Key and click Generate New Key
  6. Configure the correct API/MX/user details for the cPanel addon
  7. 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
  8. Run bulk protect from the addon in WHM
  9. Restart Bind:

    /etc/init.d/named restart

  10. 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)

Configuring PHP to support cURL and OpenSSL

The cPanel 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

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

Setting Definition Example
SpamPanel URL

The primary hostname of your cluster or CNAME of that address.

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, a notification will display in the cPanel interface to advise.

Local Cloud: https://spamfilter.example.com

Hosted Cloud: https://login.antispamcloud.com
API hostname The hostname is being used to interface with the API. This is the hostname of your primary server.

Local Cloud: spamfilter.example.com

Hosted Cloud: login.antispamcloud.com
API username The API username should be an admin or sub-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. DemoUsername1
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. DemoUserPassword123!
Primary MX The Primary MX record (MX10) See Hosted Cloud MX Records
Secondary MX The optional Secondary MX record (MX20) See Hosted Cloud MX Records
Tertiary MX The optional Tertiary MX record (MX30) See Hosted Cloud MX Records
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. See Hosted Cloud MX Records
Enable SSL for API requests

Use SSL for API requests.

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.

 Yes
Enable automatic updates

Updates are 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.

 Yes/No (Yes recommended)
Automatically add domains to the SpamFilter Create new domains in the Spam Experts Control Panel when it is being added to cPanel. Yes/No (Yes recommended)
Automatically delete domains from the SpamFilter Remove domains from the Spam Filter when they are being removed from cPanel. Yes/No (Yes recommended)
Automatically change the MX records for domains

Change the MX records in cPanel > DNS Zone Manager for your domains.

This option uses the Primary/Secondary/Tertiary MX records set here to provision the DNS for a new domain, or when you are executing Bulk Protect.

 Yes/No (Yes recommended)
Configure the email address for this domain

Automatically sets the primary contact address for the domain in the Spam Filter.

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

Yes/No (Yes recommended)
Process addon- and parked domains Add addon (alias) and parked (suspended) domains to the Spam Filter. Yes/No (Yes recommended)
Add addon- and parked domains as an alias instead of a normal domain

If unticked (and the previous one ticked), domains will be added as normal standalone domains.

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.

Yes/No (Yes recommended)
Use existing MX records as routes in the SpamFilter

If selected, 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 Workspace.

 Yes/No
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 Spam Filter delivers mail to.

 Yes/No
Redirect back to controlpanel upon logout Redirect users back to cPanel when they click the logout button in the Spam Experts interface. Yes/No
Add the domain to the SpamFilter during login if it does not exist Add the domain to the Spam Filter if the domain does not already exist at first login. Yes/No (Yes recommended)
Force changing route & MX records, even if the domain exists

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

 Yes/No (Yes recommended)
Change email routing setting "auto" to "local" in bulk protect

The cPanel “email routing” setting will be set to “local” (this server handles email) if the domain is set to “auto”.

By ticking this box, domains set to “auto” will be changed into “local”.

 Yes/No (Yes recommended)
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, the addon can be set to automatically remove the domain if it is set to anything but local or add the domain if it is switched to local. Yes/No
IP as Destination route instead of domain With this turned on all newly added domains to the Spam Filter will have destinations represented with IP addresses. With the option turned off the destinations will be hostnames. Yes/No

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.

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

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