Skip to content

CPanel User Guide

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. cpanel-3.png
  3. Scroll to the Security section of the Tools page.
  4. Click Blackwall Protection.

Availability of Components/Features

Blackwall enables hosting providers to enable or disable some components and features in this plugin. If a component or feature is not enabled, a warning message displays "This functionality is not available in your plan, contact your admin."

Enabling/disabling domain protection

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

  1. Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
  2. On the page displayed, check that the added website domain is not displaying the Not registered tag. If the Not registered tag displays, register the website in GateKeeper and then refresh this page again. cpanel-16.png
  3. To enable or disable protection for a website domain, click either the enabled or disabled radio buttons beside your listed domain. cpanel-4.png
  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, the Blackwall Protection module automatically manages and protects 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.

GateKeeper Domain Settings

Execute the following instructions in cPanel to edit the settings for any domain protected by Blackwall:

  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. cpanel-5.png
  3. From the actions available, click Settings.
  4. From the secondary menu on the Settings page, select GateKeeper. Configure a domain in cpanel
  5. Ensure that the name of the domain you wish to configure is in this field (e.g., example.com). Non-existent domains are not added, so ensure that your domain actually exists.
  6. Importantly, if you have not already done so, navigate to your DNS hosting provider (where your domain’s DNS records are managed) and update the A (IPv4) and/or AAAA (IPv6) records so that they point to the public IP address of your Blackwall GateKeeper instance. Until you do this, the status of your domain in GateKeeper is Action required.
  7. Define your application server's IP address in the UPSTREAMS field. By default, GateKeeper assumes port 80 for HTTP, but if your origin listens on a different port, append it after a colon. For example, 1.2.3.4:8080 for IPv4, or [2001:c0c0:d1d:babe:dead::1]:8080 for IPv6). If you have more than one upstream, you can separate them using commas and GateKeeper load-balances between them.
  8. GateKeeper requires a valid SSL/TLS certificate to serve your website over HTTPS. Choose one of the following options:
    • Use free Let’s Encrypt service to issue and keep certificates up to date (recommended)** - GateKeeper automatically requests and renews a certificate for your domain & listed subdomains. If you select Let's Encrypt, go directly to step 12 for your next step.
    • Use Custom Certificates ­if you already have a signed certificate and private key (for example, from a third-party CA or a wildcard certificate that you purchased), select this option to upload your files. If you choose this file, you must upload necessary files in the next two steps.
  9. If you selected Custom Certificate in step 8, now enter or paste the website's SSL certificate in PEM format. Include the complete certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
  10. If you selected Custom Certificate in step 8, enter or paste the private key associated with the SSL certificate. The private key must correspond to the certificate entered in the previous field and should include the complete PEM-formatted key.
  11. If you selected Custom Certificate in step 8 and if required by your certificate provider, enter or paste the CA certificate bundle or intermediate certificates used to establish the certificate trust chain. Leave this field blank if no CA bundle is required.
  12. Check that the Certificates are matching success message displays. This confirms that the SSL certificate and private key match and that the certificate configuration is valid.
  13. In the Load Balancer section:
    • Upstreams Use HTTPS - Check this checkbox if your origin(s) serve content over an HTTPS (port 443). When selected, GateKeeper will connect securely to the upstream rather than using HTTP. If left unchecked, GateKeeper will use HTTP (port 80) by default to fetch content from the origin.
    • Enable HTTP/3 - GateKeeper speaks 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 - Enable to automatically redirect all incoming HTTP (port 80) requests to HTTPS (port 443). When checked, GateKeeper also adds security headers to encourage browsers to use only HTTPS.
    • Force Subdomain Redirect - Select one of these radio buttons to control how requests to any listed subdomains redirect back to the canonical hostname.
    • 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.
  14. Once you have finished modifying any of the above settings, click SAVE CHANGES to apply your updates. GateKeeper immediately attempts to validate SSL certificates, update DNS checks (if necessary), and reconfigure its servers. If any required fields are missing or invalid (for example, an upstream address is unreachable), GateKeeper displays an error. If all is good, traffic starts flowing through the Blackwall GateKeeper to your upstream hosts. Once GateKeeper issues or imports the SSL certificate, it then opens the virtual host and immediately starts proxying traffic to the upstream servers that you listed.
  15. Optionally, place a check in the Disable auto synchronize checkbox to disable automatic certificate upload to Gatekeeper when the certificate installs or renews.
  16. Optionally, click the Sync certificate button to force syncronisation between cPanel and GakeKeeper. This may be used if a cPanel event calls GateKeeper to upload a new certificate, but GateKeeper is momentarily uncontactable. In this scenario, you can use the Sync certificate button to force syncronisaton with GateKeeper again.

Monitoring & Analytics

In this section, you can learn how to view statistics and event logs relating to any domain protected by Blackwall.

View Statistics for a single domain

The Statistics page gives you a simple, comprehensive, and objective snapshot of your domain's security status and associated metrics. These aggregated results and statuses present in manageable chunks of visual information that enable you to see what's going well, what needs improvement, and if necessary, where you must take action.

Alternative: View global statistics for all domains in your account

Rather than viewing statistics for a single domain, alternatively, you can view global statistics for all domains associated with your CPanel account. To do this, follow these 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 Statistics.
  4. The layout and user guide is then the same as steps 4-7 below.

To access your Statistics from your cPanel plugin:

  1. Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
  2. On the page displayed, locate your website domain, or an associated subdomain. cpanel-12.png
  3. From the actions available, click Statistics.
  4. The filters at the top of the page control what statistics display on the rest of the page. Last Hour is the default selection. To view statistics for a different time frame, click one of the other options: Last Day, Last Week, or Last Month. ../img/cpanel-14.png
  5. Alternative to the previous step, use the two date selector fields to set a start and end date for your custom time period.
  6. Click Filter Statistics to filter using your selected filter values.
  7. On this page, use the widgets displayed to learn more about the types of threats that make up the metrics for your assets.
    1. The Total widget presents a graphical display of the total web traffic, and the breakdown of what web traffic passed and failed in GateKeeper.
    2. This Bot Ratio provides a graphical breakdown of Good Bot versus Bad Bot versus Humans interactions with your web assets.
    3. The Passed vs Blocked graph visually conveys the amount of web traffic in both the passed and failed status for each bot category.

View Events for a single domain

In the context of the Blackwall platform, Events are the actions, activities, or occurrences that the platform tracks and analyzes to determine whether traffic is generated by a human or a bot. Events are fundamental to Blackwall's detection capabilities, as they provide the raw data needed to make critical decisions about suspicious or malicious behavior.

Alternative: View global events for all domains in your account

Rather than viewing events for a single domain, alternatively, you can view global events for all domains associated with your CPanel account. To do this, follow these 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-18.png

  3. From the tabs available, select Events.
  4. The layout and user guide is then the same as steps 4-7 below.

To access and view Events for your selected domain in cPanel, perform the following tasks:

  1. Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
  2. On the page displayed, locate your website domain, or an associated subdomain. cpanel-5.png
  3. From the actions available, click Events.
  4. The filters at the top of the page control what events display on this page. Last Hour is the default selection. To view events for a different time frame, click one of the other options: Last Day, Last Week, or Last Month. ../img/cpanel-14.png
  5. Alternative to the previous step, use the two date selector fields to set a start and end date for your custom time period.
  6. Click Filter Statistics to filter using your selected filter values.
  7. View all traffic events in the filtered table that displays.
  8. Optionally, click Show More to expand the table to show more events.

Performance

Choose how GateKeeper should cache your site’s assets:

  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. cpanel-5.png
  3. From the actions available, click Settings.
  4. On the Settings page, click the Performance tab. cpanel-20.png
  5. In the Content Caching section, choose how GateKeeper should cache your site’s assets:
    • Enable static resources caching - 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.
    • Enable dynamic resources caching - 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).
  6. Click Save Changes to save your changes.

Security settings

After enabling protection, you can use the plugin in the same way as users of the main Blackwall platform. Execute the following instructions in cPanel to edit the security settings for any domain protected by Blackwall:

  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. cpanel-5.png
  3. From the actions available, click Settings.
  4. On the Settings page, click the Security tab. cpanel-7.png

  5. From the eight core rules displayed in the Bot Mitigation (S1) section, locate the rule that you wish to modify. For the rule that you choose to modify, select a radio button that corresponds to your desired behaviour. The radio buttons possible are:

    • Grant access
    • Deny access
    • Use CAPTCHA (only available for some rules)

    Default Core Rule settings

    Blackwall recommends keeping Blackwall's default Core Rule settings, unless you have a particular use case that necessitates a change.

  6. In the L7 DDoS Protection (S2) section, place a check in the checkbox that corresponds with one or both DDoS options:

    • Mitigate DDoS attacks - Limits the number of simultaneous connections and the rate of requests from a single IP to help prevent volumetric or application-layer DDoS floods. Requires bot protection enabled first.
    • Advanced DDoS protection - If enabled (and if bot protection is already on), 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. In the Web Application Firewall (S3) section, you can choose to Enable bot protection. When checked, GateKeeper’s Web Application Firewall (WAF) and Bot Management services inspect incoming requests to block known malicious bots, scrapers, and automated attacks.

  8. Optionally, in the CMS section, place a check in the checkbox that corresponds to any ruleset that you wish to enable.

  9. Click Save Changes to save your changes.

Custom Rules

You can override default rules, as Custom Rules always have priority over any other type of rule. You can add a new custom rule at any time, by performing the following actions:

  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. cpanel-5.png
  3. From the actions available, click Settings.
  4. On the Settings page, click the Custom Rules tab. cpanel-9.png
  5. Name your rule, by typing a unique name into the RULE NAME field.

  6. Set the trigger conditions for your new rule:

    1. In the FIELD dropdown menu, select from the listed criteria.

      Click to review the criteria options

      • Autonomous System Number - type the AS number using numbers only, but do not include a prefix with AS/ASN abbreviations.
      • User-Agent - the corresponding HTTP header, sent by any software that makes a request to your server. You could use this condition to block/allow requests from browsers, like Google Chrome, Mozilla Firefox (or their mobile versions), CLI tools like wget or curl, programming languages libraries, like Urllib or requests in Python, Go Http Client, libwww-perl, etc. You can also try exploring the world of various User-Agents to get more examples via special databases. We recommend checking out whatismybrowser.com or useragentstring.com.
      • Country Code - used to restrict access based on visitor geography.
      • IP Address - we advise to whitelist administrator/developer/QA IP addresses (IPv4 or IPv6 - Blackwall supports both).
      • Referrer URL - a browser sends the location of where a link to your site was clicked in a special Referer HTTP Header.
      • Internet Service Provider - firstly, type the ISP name and secondly, type the AS number using numbers only.
      • HTTP Header - condition does the same as the two headers above, but you could use any HTTP header here, even non-standard ones.
      • URI Path - this condition allows you to grant or deny requests sent to certain URLs on your site.
      • Domain - our service automatically protects the subdomains for your main domain name.

    2. In the LOGICAL CONDITION dropdown menu, choose an operator. The operator options available in this dropdown are pre-defined based upon the criterion selected in the previous step.

      Click to review the operator options

      • Is / Is not - this means a strict match
      • Contains / Not contains - a partial match to the rule string
      • Greater than / Less than - applicable to number values only
      • Is any of - a strict match to stated possible values
      • Matches to expression - matches a regular expression

    3. Type a value into the FIELD VALUE text field. This is the value for the corresponding operator selected in the previous step.

  7. Optionally, click Add Condition and repeat the previous step to add more than one condition to a rule.

  8. Optionally, to remove a condition that you don't want associated with your rule, click Remove Condition beside the condition that you wish to delete.

  9. Now choose an action to trigger by your condition(s). Choose from the following actions:

    Click to review the actions available

    • Deny access - access denied to your website.
    • Grant access - access granted to your website.
    • Use CAPTCHA - access granted to your website, but only after successful completion of a CAPTCHA challenge.
    • Redirect to: - regular access denied and the traffic redirects to either a particular page in your website, or another website page entirely. After selecting this action, you must provide the URL of the redirection target page.
    • Limit request rate by: - access requests from the same source are restricted within the bounds set in the additional fields for this action. After selecting this action, you must state how many requests that you will allow within a stated period of time.

  10. Click Add Rule to add your new rule.

  11. Ensure that your new rule is active.
    1. In the Custom Rules list, locate your new rule. cpanel-10.png
    2. Make sure that the rule activation toggle switch is set to ON. In the future, you can also choose to set the toggle switch to OFF to deactivate the rule.
    3. Optionally, you can delete a rule by clicking Delete.

Note

For the FIELD VALUE entry for step 6a and the Redirect option for available actions in step 9, you can add URLs in two ways. You can:

  • Add the URL as an absolute URL including the transfer protocol; e.g. http://anywebsite.com/any-page
  • Alternatively, you can add the URL as a relative URL, so long as the URL is in the same website as the one for which you are creating a custom rule; e.g. /any-page. In effect, this is the same as using http://your-protected-website.com/any-page.

Once created, you cannot edit custom rules. If you need to change a rule, add a new rule with the new configuration desired and then remove the old rule.

Troubleshooting

If GateKeeper does not display the correct status, ensure that your domain’s DNS is updated correctly. The A (IPv4) and/or AAAA (IPv6) records must point to the public IP address of your Blackwall GateKeeper instance. Otherwise, you will receive an error similar to this: DNS Error

Feedback