WHM / cPanel

Installing the plugin

BotGuard provides a WHM / cPanel integration plugin. When the plugin is installed, the Blackwall Apache web server protection module is activated, and WHM/cPanel displays configuration options for both WHM administrators and cPanel users.

The WHM/cPanel plugin has historically run on CentOS, but most modern deployments now use AlmaLinux or Rocky Linux as drop-in replacements.
All of these distributions, as well as RHEL, use the RPM package format and are binary compatible. This means the RPM instructions below apply to any of these systems. Ubuntu is also supported, though perhaps less commonly used in production environments.

The module is installed and updated in the standard way, using an SSH connection to the WHM server. Choose a tab below that corresponds to your operating system:

RPM (AlmaLinux/Rocky Linux/RHEL)Debian (Ubuntu)

1. Import the BotGuard package digital signature key. This ensures that the packages you install are verified and have not been tampered with:
   

   sudo rpm --import https://repo.botguard.net/botguard.gpg
   

2. Add the BotGuard repository to your system. This tells your package manager where to find BotGuard packages:
   

   sudo yum-config-manager --add-repo https://repo.botguard.net/BotGuard.repo
   

3. Clear the package cache. This ensures that outdated metadata is removed before installing:
   

   sudo yum clean all
   

4. Install the Blackwall WHM / cPanel plugin and required Apache modules. The ea-apache24-mod_botguard module will also be installed as a dependency:
   

   sudo yum install --disablerepo botguard --enablerepo botguard-cloudlinux ea-apache24-botguard-mod_ssl ea-apache24-mod_botguard
   sudo yum install botguard-whm
   

5. Restart Apache to apply changes:

   sudo /usr/local/cpanel/scripts/restartsrv_httpd
   

1. Import the BotGuard package digital signature key. This ensures that the packages you install are verified and have not been tampered with:

   wget -qO - https://repo.botguard.net/botguard.gpg | sudo apt-key add -
   

2. Add the BotGuard repository to your system. This tells your package manager where to find BotGuard packages:
   

   echo "deb https://repo.botguard.net/ubuntu stable main" | sudo tee /etc/apt/sources.list.d/botguard.list
   

3. Update the package list.
   

   sudo apt update
   

4. Install the Blackwall WHM / cPanel plugin. This will also install the Apache module as a dependency:

   sudo apt install blackwall-protection-whm
   

5. Restart Apache to apply changes:

   sudo systemctl restart apache2
   

Configuring the plugin

The plugin is disabled after performing the installation steps above. Before using the plugin, it must be configured. To configure the plugin, perform the following steps:

1. Log into your WHM interface:
   1. Using your preferred browser, enter the IP address or domain name followed by the 2087 service port in your preferred browser (for example, https://198.51.100.1:2087).
   2. When the login screen displays, enter your WHM username in the Username field.
   3. Enter your password in the Password field.
   4. Click Log in.
2. In the left sidebar, scroll to the Plugins section and click Blackwall Protection. Alternatively, use the search bar at the the top of the sidebar to search for Blackwall Protection.
3. Set up the plugin using the following steps. After execution, if any error is displayed, check the API key and server addresses.
   1. Paste your API Key, which is copied from your Blackwall dashboard. Refer to Blackwall account credentials for guidance how to access your API key.
   2. The plugin should automatically fetch the IP addresses of Gatekeeper servers via its DNS results, but if it does not, manually enter your Gatekeeper server IP address(es) in this API server address field.
   3. In the Upsell link field, paste the full URL (include https://) of the page where you want cPanel users to land if they try to access premium/paid Blackwall services.
   4. Click Apply.
4. To create a package with Blackwall features, perform the following actions:
   1. In the left sidebar, scroll to the Packages section and click Add a Package. Alternatively, use the search bar at the the top of the sidebar to search for Packages and from the filtered sidebar, click Add a Package.
   2. After completing the package-related configuration fields, ensure to place a check/tick in the check box that corresponds with Blackwall Protection.
   3. New options now display to enable you to configure your Blackwall protection. Ensure to place a check/tick in the check box that corresponds with Gatekeeper.
   4. From the radio button options provided, select one type of protection to implement in your package:
      • Monitoring-only Mode
      • Basic Protection
      • Advanced Protection
   5. If you selected Advanced Protection in the previous step, then place a check in the checkbox that corresponds with your preferred option between DDoS Protection and Cache.
   6. Click Add to complete configuration of your new package.

Note

You can create various packages with a combination of package settings. Then apply the appropriate packages to cPanel accounts according to their preferences. You can also edit existing packages to add Blackwall Protection.

Following successful execution of the previous steps, each associated cPanel account gains access to the Blackwall Protection settings in the cPanel web control panel. Refer to Using the plugin for instructions how to access and use the plugin.

Using the plugin

Accessing the plugin

Following successful execution of the previous steps, each user of this WHM server gains access to the Blackwall Protection settings in the cPanel web control panel. To access these settings:

1. Log in to the cPanel web control panel that you have installed Blackwall to in previous steps.
2. From the left sidebar, click Tools.
3. Scroll to the Security section of the Tools page.
4. Click Blackwall Protection.

Enabling/disabling domain protection

Now that the plugin is installed and configured, you can enable or disable protection for the domains and associated subdomains:

1. Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
2. On the page displayed, scroll the list of added website domains and associated subdomains.
3. To enable or disable protection for a website domain, click either the enabled or disabled radio buttons beside each listed domain.
4. To enable protection of listed subdomains, place a check/tick in the Registered checkbox beside each subdomain. To disable subdomain protection, remove this check/tick.
5. Click Apply to execute any changes made.
6. If enabling protection for the first time, ensure that you also configure your domain correctly by navigating to your domain's DNS settings. You can choose one of the following approaches:
   • Automatic DNS configuration (recommended) — When DNS management of your domain is delegated to your cPanel, Blackwall Protection module will automatically manage and protect your DNS records for your website and its subdomains.
   • Manual DNS configuration — Ensure sure that your domain has A/AAAA records pointing towards to your Gatekeeper IP addresses.

Using the plugin

After enabling protection, you can use the plugin in the same way as users of the main Blackwall platform. With the exception of the appearance of the plugin, the functionality is largely identical.

1. Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
2. On the page displayed, scroll the list of added website domains.
3. From the actions available, choose one of the following and refer to the appropriate documentation for the main Blackall platform. The links display the relevant content within the Blackwall platform documentation, which is almost identical to the plugin functionality.
   • Settings - Refer to Core rules, Rulesets, and Custom rules documentation for guidance.
   • Statistics - Refer to Statistics documentation, which although not exactly alike, contains the a subset of the same components and functionality.
   • Events - Refer to Events documentation.

Uninstalling the Plugin

Uninstall the plugin from your system by selecting the tab which corresponds to your operating system:

RPM (AlmaLinux/Rocky Linux/RHEL)Debian (Ubuntu)

1. To uninstall and remove the package:
   

   sudo yum remove botguard-whm
   

2. To remove configuration files:
   

   sudo yum remove botguard-whm --noautoremove
   

1. To uninstall and remove the package:
   

   sudo dpkg -r blackwall-protection-whm
   

2. To remove configuration files:
   bash sudo dpkg -P blackwall-protection-whm

Note

For informational purposes,the plugin files install to the following directories:

• WHM: /usr/local/cpanel/whostmgr/docroot/cgi/blackwall-protection/
• cPanel: /usr/local/cpanel/base/3rdparty/blackwall-protection/

Feedback