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:

Log in to the cPanel web control panel that you have installed Blackwall to in previous steps.
From the left sidebar, click Tools.
Scroll to the Security section of the Tools page.
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:

Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
On the page displayed, scroll the list of added website domains and associated subdomains.
To enable or disable protection for a website domain, click either the enabled or disabled radio buttons beside each listed domain.
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.
Click Apply to execute any changes made.
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.

Settings

After enabling protection, you can use the plugin in the same way as users of the main Blackwall platform. Except for the appearance of the plugin, the functionality is mostly identical.

Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
On the page displayed, scroll the list of added website domains.
From the actions available, click Settings.
From the secondary menu on the Settings page, select Core Rules.
1. From the eight core rules displayed, 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 on some rules)
2. Click Save Changes to save your changes.
Default Core Rule settings

Blackwall recommends keeping Blackwall's default Core Rule settings, unless you have a particular use case that necessitates a change.
Optionally, from the secondary menu on the Settings page, select Rulesets.
1. Locate the ruleset that you wish to switch on or off.
2. For the ruleset that you wish to enable or disable, switch the associated toggle switch to ON or OFF.
3. Click APPLY to save your changes.
Optionally, from the secondary menu on the Settings page, select Custom Rules. You can override default rules, as Custom Rules always have priority over Core Rules and Rulesets. You can add a new Custom Rule at any time, by perform the following actions:
1. Name your rule, by typing a unique name into the RULE NAME field.
2. Set the trigger conditions for your 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). These people often use custom software and send unusual requests to the site, which might be blocked otherwise. Please be sure to whitelist your site’s uptime monitor IP address. This condition supports CIDR notation to list IP subnets, like 123.123.123.123/24. You can also easily list different subnets in a single rule using the ‘Is any of’ match type (separating each subnet with a comma followed by a space, for example: first, second, third, ).
    - Referrer URL - a browser sends the location of where a link to your site was clicked in a special "Referer HTTP Header. One common Custom Rule, which might be useful for you, is to block visitors with an empty ‘Referer’ header. When the ‘Referer’ header is empty, it means that the client made a direct request to the site, and didn’t follow any link or perform any search request prior to the visit. Most of the time it’s fine, because it means the user typed your site address from memory, but sometimes it’s an indicator of bot traffic.
    - Internet Service Provider - firstly, type the ISP name and secondly, type the AS number using numbers only. Do not include a prefix with AS/ASN abbreviations.
    - 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. You should omit the scheme and domain name to use it. For example, a bot is sending requests to URL https://www.example.net/some/path/resource.html, in which case you would use /some/path/resource.html for the rule. Commonly used with the Match to expression match type to cover files and directories via Regular Expressions.
    - Domain - our service automatically protects the subdomains for your main domain name. But sometimes you might need to apply a Custom Rule to some specific subdomains, this is where you should use this condition.
  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 corresonding operator selected in the previous step.
3. Optionally, click Add Condition and repeat step 'b' to add more than one condition to a rule. You can add multiple conditions to a rule, but note that when adding more than one condition, all conditions process with the logical operator AND. This means that all listed conditions must trigger before the associated action executes.
4. 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.
5. 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.
6. Click Add Rule to add your new rule.
7. Ensure that your new rule is active.
  1. In the Custom Rules list, locate your new rule.
  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 '2-b-i' and the Redirect option for available actions in step 3, 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 rules. If you need to change a rule, add a new rule with the new configuration desired and then remove the old rule.

GateKeeper Domain Settings

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

Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
On the page displayed, scroll the list of added website domains.
From the actions available, click Settings.
From the secondary menu on the Settings page, select GateKeeper.
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.
Select one of these radio buttons to control how requests to any listed subdomains redirect back to the canonical hostname.
Define your application server's IP address (or hostname + port) 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.
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.
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.
- Alternatively, use BuyPass for your certificate management.
- 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.
Optionally, place a check in the Disable auto synchronize checkbox to disable automatic certificate upload to Gatekeeper when the certificate installs or renews.
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.
The Website Options section contains a series of checkboxes under sub-headings. These checkboxes enable you to configure how GateKeeper interacts with your domains. Internet protocols - Control advanced HTTP/encryption features:
- 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.
- Enable 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.
Content Caching - Decide 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).
Security - Configure GateKeeper’s built-in bot management and DDoS mitigation features:
- 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.
- 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.
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.
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.

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:

Statistics

The Statistics page gives you a simple, comprehensive, and objective snapshot of your security status and provides 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. To access your Statistics from your cPanel plugin:

Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
On the page displayed, scroll the list of added website domains.
From the actions available, click Statistics.
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.
Alternative to the previous step, use the two date selector fields to set a start and end date for your custom time period.
Click Filter Statistics to filter using your selected filter values.
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.

Events

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. To access and view Events for all your listed assets in cPanel, perform the following tasks:

Access the Blackwall Protection plugin by following the steps in Accessing the plugin.
On the page displayed, scroll the list of added website domains.
From the actions available, click Events.
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.
Alternative to the previous step, use the two date selector fields to set a start and end date for your custom time period.
Click Filter Statistics to filter using your selected filter values.
View all traffic events in the filtered table that displays.
Optionally, click Show More to expand the table to show more events.

Feedback