Skip to content

Install WHM/cPanel

This integration works with HSPs, Resellers, and Marketplaces.

Installing the plugin

We recommend managing Blackwall via GateKeeper directly or one of Blackwall's integration modules, not both. Running them concurrently can cause configuration conflicts and complicate troubleshooting. Pick one interface and use it consistently for all changes. This matters especially in hosted environments, where service providers don't have access to customer integration module instances.

BotGuard provides a WHM/cPanel integration plugin that enables hosting providers to offer Blackwall protection to their customers. After installing the plugin, a WHM administrator can create bespoke Blackwall packages by selecting the components and component functions to include, based on the required service level, customer needs, and budget.

When a package is assigned to a customer account, the corresponding Blackwall components and features are made available to the customer. cPanel users can then access and configure only the Blackwall features made available through their assigned package.

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 system:

  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 blackwall-protection-whm

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

    curl -fsSL "https://repo.botguard.net/botguard.gpg" | gpg --dearmor -o /usr/share/keyrings/botguard.gpg

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

    echo "deb [signed-by=/usr/share/keyrings/botguard.gpg] https://repo.botguard.net/debian stable main" | tee /etc/apt/sources.list.d/botguard.list

  3. Update the package list.

    apt update

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

    apt install -y blackwall-protection-whm

Configuring the plugin

The plugin is disabled after performing the installation steps above. Before using the plugin, it must be configured using one of two possible methods:

  • Configure plugin via the UI.
  • Configure plugin using a configuration file.

Click the appropriate tab below to read instructions for the chosen configuration method:

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://192.0.2.1:2087). cpanel-2.png
    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. cpanel-1.png
  3. From the tabs available, select Settings.
  4. 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. Paste your API server address. The plugin uses this to automatically fetch the IP addresses of Gatekeeper servers via its DNS results.
    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.
  5. Optionally, review the plugin version and active GateKeeper API components, which is particularly useful for validation, support, and system diagnostics.

  6. 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. cpanel-6.png
    2. After completing the general domain-related configuration fields for the package, to enable Blackwall protection for the customer's domain, place a check/tick in the checkbox that corresponds with Blackwall Protection. New options now reveal to enable you to configure Blackwall protection components and features that you wish to make available to your customer.
    3. In the Blackwall Protection panel, confirm that protection is enabled.
    4. For the section Monitoring & Analytics, Traffic Analytics (A1) is included as a mandatory monitoring component and cannot be edited/cleared.

    5. For Bot Mitigation (S1) in the Security section:

      1. Place a check in the Bot Mitigation (S1) checkbox, if you wish to include this component.

      2. Once selected in the previous step, options for eight core rules display. Locate the rule that you wish to modify.

        Description of Blackwall core rules

        We recommend that you grant access to the following:

        • search_engines - Search engine crawlers such as Google, Bing, Yahoo, and other indexing services that scan websites to discover and rank content in search results. These bots are generally considered trusted traffic and are important for SEO visibility, search discoverability, and content indexing. Administrators can choose to allow or deny access depending on business or security requirements.

        • social_networks - Bots and crawlers operated by social media platforms such as Facebook, X (Twitter), LinkedIn, and others. These services typically access websites to generate link previews, retrieve metadata, or analyse shared content. Allowing these visitors helps ensure correct rendering of shared links and social media integrations.

        • services_and_payments - Automated traffic originating from recognised cloud-based services, infrastructure providers, or monitoring platforms. This category may include uptime monitoring tools, performance scanners, analytics platforms, and other legitimate cloud-hosted services. Depending on your environment, these services may be required for monitoring, integrations, or operational visibility.

        • humans - Typical human visitors accessing the website through desktop browsers, mobile devices, or office networks. This category represents normal end-user traffic and is generally expected to have unrestricted access to website resources. Additional protections, such as content encryption, can be applied to secure content delivery and reduce automated analysis of sensitive page content.

        We recommend that you deny access in the remaining four rules:

        • content_scrapers - Automation tools designed to collect, copy, analyse, or archive website content at scale. These visitors are commonly associated with data scraping, competitive intelligence gathering, AI dataset collection, or automated content harvesting. Depending on business requirements, administrators may choose to block these visitors, challenge them with CAPTCHA, or apply content encryption to help protect sensitive or proprietary content.

        • emulated_humans - Advanced automation frameworks and next-generation bots that attempt to mimic legitimate browser behaviour in order to bypass traditional bot detection mechanisms. These visitors may simulate mouse movement, browser execution, session handling, or other human-like interactions. Because these bots are often associated with credential abuse, scraping, or automated attacks, they typically require stricter mitigation measures such as CAPTCHA enforcement, encryption, or access denial.

        • suspicious_behaviour - Visitors exhibiting unusual, abnormal, or potentially abusive behaviour patterns detected by Blackwall’s analysis engine. This category may include excessive request rates, behavioural anomalies, suspicious navigation patterns, or activity commonly associated with automated abuse or account compromise attempts. Administrators can apply additional protections such as CAPTCHA challenges, encryption, or outright blocking to reduce the risk posed by suspicious traffic.

      3. For the rule that you choose to modify, select a dropdown field that corresponds to your desired behaviour. The available dropdown options are:

        • Grant access
        • Deny access

    6. For L7 DDoS Protection (S2) in the Security section, select one type of protection to implement in your package by placing a check in the corresponding checkbox:

      • ddos_protection - Enables basic Layer 7 DDoS mitigation for the protected domain by limiting the number of simultaneous connections and the rate of requests from a single IP to help prevent volumetric or application-layer DDoS floods.
      • ddos_protection_advanced - Enables additional Layer 7 DDoS protection for more advanced application-layer attacks. If enabled, GateKeeper will block attacking IPs at the firewall level for the entire cluster—returning a TCP RST or UDP rejection instead of serving HTTP 403 pages. Use this only if your site has experienced large-scale DDoS events.
    7. Optionally, place a check in the Web Application Firewall (S3) checkbox in the Security section. Then use the dropdown field to select whether you want to grant or deny associated security_issues.

    8. Optionally, place a check in the Custom Rules (S4) checkbox in the Security section. Then use the dropdown field to select whether you want to enable or disable the custom-rules feature.

      Custom Rules are different to Blackwall's Core Rules. Whilst our default Core Rules greatly decrease bot traffic for your website(s), some visitor behavior might still present a cause for concern. This is where our Custom Rules engine can help you to eliminate those visitors from accessing your website. The Custom Rules engine may be used for bespoke purposes, but the main two purposes are:

      • Whitelisting (unblocking) of currently blocked services and clients.
      • Blocking of services and clients that currently have access to your site.

    9. In the Performance section, select Content Caching (P1) when the package should include Blackwall content-caching capabilities. Then from the available features, optionally choose one or both:

      • cache_dynamic_pages - If checked, GateKeeper also caches HTML pages and other 'dynamic' content for a configurable short period. Use with caution: caching dynamic content may cause delays in showing newly published data (e.g., blog posts, user-specific pages).
      • cache_static_files - If checked, GateKeeper caches images, CSS, JavaScript, and other static files locally on the edge. This speeds up asset delivery and reduces load on your origin server.

    10. In the Common Features section, configure the default feature settings to apply to websites assigned to the package. Depending on the available Blackwall API functions, these settings can include:

      • early_hints — Allows GateKeeper to send HTTP 103 “Early Hints” responses during the initial TLS handshake, so that browsers can start preloading resources (e.g., CSS/JS) before the final HTML is delivered. This improves load times, leading to a faster browsing experience.
      • ssl_certificates — Specifies the SSL certificate configuration, such as letsencrypt.
      • enable_http3 — Enables HTTP/3 support for compatible browsers and clients. GateKeeper will speak HTTP/3 (QUIC/UDP) to compatible clients, improving performance on modern browsers and mobile devices. Leave unchecked if you need to disable HTTP/3 for compatibility or DDoS concerns.
      • force_https — rRdirects HTTP requests to HTTPS.
      • force_subdomain_redirect — Enables the configured subdomain redirection behaviour.
      • https_upstream — Uses HTTPS when Blackwall connects to the upstream server. Clear this checkbox if Blackwall should connect to the upstream server over HTTP.

    11. In the Component Common Features section, select the default website_status to apply to associated websites, such as active or paused.

    12. Review the selected components and optional features, and click Add to complete configuration of your new package.

The selected components and features determine which Blackwall security capabilities are assigned to websites using this package and made available to the corresponding cPanel users. These values are saved as the package defaults and applied to new and existing Blackwall websites associated with the package.

Note

You can create multiple packages containing different combinations of Blackwall components and default feature settings. This enables you to provide different protection levels according to customer requirements, service tiers, and budgets.

When a package is assigned to a cPanel account or domain, its selected components and default settings are applied to the associated Blackwall website. Changing the assigned package updates the Blackwall capabilities available to that customer.

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.

Blackwall facilitates automated deployment of our cPanel module, which is ideal for hosting providers who often deploy many servers per day. To enable UI configuration to be overridden by a configuration file, perform the following steps:

  1. On each cPanel server where the Blackwall module is installed, use the following commands in sequence to create a Blackwall directory and restrict access to the root user:

    mkdir -p /var/cpanel/config/blackwall

    chmod 0700 /var/cpanel/config/blackwall

    chown root:root /var/cpanel/config/blackwall

  2. Create a server-wide JSON configuration file with content similar to this example: 

        "blackwall-protection-api-key": "YOUR-API-KEY-HERE",
    "blackwall-protection-api-address": "YOUR-GK-API-ADDRESS-HERE",
    "upsell-link": "https://my.store.com/full-protection-now",
    "server-registration-status": true

  3. Save the configuration file to the Blackwall directory created in step 1. Name the file: config.json.

    Note

    • Where the file exists, it will be used and the GK configuration screen in the UI will be hidden.
    • If the file is removed at some point in the future, at the next cPanel login, you will be required to provide configuration via the UI, or replace the configuration file to the same location.
    • If the file is created after configuration in the UI, note that the configuration file settings take precedence; i.e. the file always overrides UI configuration.

  4. To create the package, you still must 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.0:2087). cpanel-2.png
    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.

  5. 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. cpanel-6.png
    2. After completing the general domain-related configuration fields for the package, to enable Blackwall protection for the customer's domain, place a check/tick in the checkbox that corresponds with Blackwall Protection. New options now reveal to enable you to configure Blackwall protection components and features that you wish to make available to your customer.
    3. In the Blackwall Protection panel, confirm that protection is enabled.
    4. For the section Monitoring & Analytics, Traffic Analytics (A1) is included as a mandatory monitoring component and cannot be edited/cleared.

    5. For Bot Mitigation (S1) in the Security section:

      1. Place a check in the Bot Mitigation (S1) checkbox, if you wish to include this component.

      2. Once selected in the previous step, options for eight core rules display. Locate the rule that you wish to modify.

        Description of Blackwall core rules

        We recommend that you grant access to the following:

        • search_engines - Search engine crawlers such as Google, Bing, Yahoo, and other indexing services that scan websites to discover and rank content in search results. These bots are generally considered trusted traffic and are important for SEO visibility, search discoverability, and content indexing. Administrators can choose to allow or deny access depending on business or security requirements.

        • social_networks - Bots and crawlers operated by social media platforms such as Facebook, X (Twitter), LinkedIn, and others. These services typically access websites to generate link previews, retrieve metadata, or analyse shared content. Allowing these visitors helps ensure correct rendering of shared links and social media integrations.

        • services_and_payments - Automated traffic originating from recognised cloud-based services, infrastructure providers, or monitoring platforms. This category may include uptime monitoring tools, performance scanners, analytics platforms, and other legitimate cloud-hosted services. Depending on your environment, these services may be required for monitoring, integrations, or operational visibility.

        • humans - Typical human visitors accessing the website through desktop browsers, mobile devices, or office networks. This category represents normal end-user traffic and is generally expected to have unrestricted access to website resources. Additional protections, such as content encryption, can be applied to secure content delivery and reduce automated analysis of sensitive page content.

        We recommend that you deny access in the remaining four rules:

        • content_scrapers - Automation tools designed to collect, copy, analyse, or archive website content at scale. These visitors are commonly associated with data scraping, competitive intelligence gathering, AI dataset collection, or automated content harvesting. Depending on business requirements, administrators may choose to block these visitors, challenge them with CAPTCHA, or apply content encryption to help protect sensitive or proprietary content.

        • emulated_humans - Advanced automation frameworks and next-generation bots that attempt to mimic legitimate browser behaviour in order to bypass traditional bot detection mechanisms. These visitors may simulate mouse movement, browser execution, session handling, or other human-like interactions. Because these bots are often associated with credential abuse, scraping, or automated attacks, they typically require stricter mitigation measures such as CAPTCHA enforcement, encryption, or access denial.

        • suspicious_behaviour - Visitors exhibiting unusual, abnormal, or potentially abusive behaviour patterns detected by Blackwall’s analysis engine. This category may include excessive request rates, behavioural anomalies, suspicious navigation patterns, or activity commonly associated with automated abuse or account compromise attempts. Administrators can apply additional protections such as CAPTCHA challenges, encryption, or outright blocking to reduce the risk posed by suspicious traffic.

      3. For the rule that you choose to modify, select a dropdown field that corresponds to your desired behaviour. The available dropdown options are:

        • Grant access
        • Deny access

    6. For L7 DDoS Protection (S2) in the Security section, select one type of protection to implement in your package by placing a check in the corresponding checkbox:

      • ddos_protection - Enables basic Layer 7 DDoS mitigation for the protected domain by limiting the number of simultaneous connections and the rate of requests from a single IP to help prevent volumetric or application-layer DDoS floods.
      • ddos_protection_advanced - Enables additional Layer 7 DDoS protection for more advanced application-layer attacks. If enabled, GateKeeper will block attacking IPs at the firewall level for the entire cluster—returning a TCP RST or UDP rejection instead of serving HTTP 403 pages. Use this only if your site has experienced large-scale DDoS events.
    7. Optionally, place a check in the Web Application Firewall (S3) checkbox in the Security section. Then use the dropdown field to select whether you want to grant or deny associated security_issues.

    8. Optionally, place a check in the Custom Rules (S4) checkbox in the Security section. Then use the dropdown field to select whether you want to enable or disable the custom-rules feature.

      Custom Rules are different to Blackwall's Core Rules. Whilst our default Core Rules greatly decrease bot traffic for your website(s), some visitor behavior might still present a cause for concern. This is where our Custom Rules engine can help you to eliminate those visitors from accessing your website. The Custom Rules engine may be used for bespoke purposes, but the main two purposes are:

      • Whitelisting (unblocking) of currently blocked services and clients.
      • Blocking of services and clients that currently have access to your site.

    9. In the Performance section, select Content Caching (P1) when the package should include Blackwall content-caching capabilities. Then from the available features, optionally choose one or both:

      • cache_dynamic_pages - If checked, GateKeeper also caches HTML pages and other 'dynamic' content for a configurable short period. Use with caution: caching dynamic content may cause delays in showing newly published data (e.g., blog posts, user-specific pages).
      • cache_static_files - If checked, GateKeeper caches images, CSS, JavaScript, and other static files locally on the edge. This speeds up asset delivery and reduces load on your origin server.

    10. In the Common Features section, configure the default feature settings to apply to websites assigned to the package. Depending on the available Blackwall API functions, these settings can include:

      • early_hints — Allows GateKeeper to send HTTP 103 “Early Hints” responses during the initial TLS handshake, so that browsers can start preloading resources (e.g., CSS/JS) before the final HTML is delivered. This improves load times, leading to a faster browsing experience.
      • ssl_certificates — Specifies the SSL certificate configuration, such as letsencrypt.
      • enable_http3 — Enables HTTP/3 support for compatible browsers and clients. GateKeeper will speak HTTP/3 (QUIC/UDP) to compatible clients, improving performance on modern browsers and mobile devices. Leave unchecked if you need to disable HTTP/3 for compatibility or DDoS concerns.
      • force_https — rRdirects HTTP requests to HTTPS.
      • force_subdomain_redirect — Enables the configured subdomain redirection behaviour.
      • https_upstream — Uses HTTPS when Blackwall connects to the upstream server. Clear this checkbox if Blackwall should connect to the upstream server over HTTP.

    11. In the Component Common Features section, select the default website_status to apply to associated websites, such as active or paused.

    12. Review the selected components and optional features, and click Add to complete configuration of your new package.

The selected components and features determine which Blackwall security capabilities are assigned to websites using this package and made available to the corresponding cPanel users. These values are saved as the package defaults and applied to new and existing Blackwall websites associated with the package.

Note

You can create multiple packages containing different combinations of Blackwall components and default feature settings. This enables you to provide different protection levels according to customer requirements, service tiers, and budgets.

When a package is assigned to a cPanel account or domain, its selected components and default settings are applied to the associated Blackwall website. Changing the assigned package updates the Blackwall capabilities available to that customer.

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.

Uninstalling the Plugin

Uninstall the plugin from your system by selecting the option which corresponds with your wishes and your operating system.

What happens during uninstallation?

The table below shows what is removed during each uninstall method.

Uninstallation step Description Full uninstall Limited uninstall (using --keep-config)
Hook Removal Unregister all cPanel/WHM hooks associated with the plugin. âś… âś…
Binary Removal Delete all plugin binaries and scripts from the system. âś… âś…
Restore DNS Zones Revert all protected domains to their original DNS records using local backups. ✅ ❌
GateKeeper Cleanup Remove all registered domains and subaccounts from the GateKeeper API. ✅ ❌
Configuration Removal Delete all configuration files and DNS backups in /var/cpanel/config/blackwall. ✅ ❌

The recommended method to uninstall the plugin is using the built-in script:

  • Standard uninstallation (removes all data and restores DNS): sudo blackwall-uninstall

  • Uninstall while keeping configuration files and DNS backups: sudo blackwall-uninstall --keep-config

Uninstall using package managers

You can also use standard package managers. To preserve configuration files, use the KEEP_CONFIG environment variable:

To uninstall and remove the package and configuration files: 1. Uninstall and remove the package:

yum remove blackwall-protection-whm
2. Remove configuration files:
yum remove blackwall-protection-whm --noautoremove

Alternatively, to uninstall but keep configuration files and DNS backups: 

KEEP_CONFIG=1 yum remove blackwall-protection-whm

To uninstall and remove the package and configuration files:

apt-get remove blackwall-protection-whm

To uninstall but keep configuration files and DNS backups: 

KEEP_CONFIG=1 apt-get remove 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