Skip to content

CPanel user settings

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."

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 enabled, GateKeeper also adds security headers and rewrites http:// references in response bodies to https://. The recommended long-term solution is to configure the application to generate HTTPS URLs directly.

      Disable response-body rewriting while retaining Force HTTPS

      If you need to keep HTTP-to-HTTPS redirection enabled but prevent GateKeeper from rewriting http:// URLs in response bodies:

      1. Back up the domain configuration:

        cp -a /opt/nginx/etc/nginx/sites-enabled/<domain> /opt/nginx/etc/nginx/sites-enabled/<domain>.bak

      2. Find each occurrence of:

        sub_filter 'http://' 'https://';

      3. For each occurrence found, comment it out:

        # sub_filter 'http://' 'https://';

      4. Do not modify:

        proxy_redirect http:// https://;

        Leave Force HTTPS enabled.

      5. Reload the NGINX configuration or restart the service.

      Warning

      HTTP URLs generated by the application may cause mixed-content warnings if they are used to load browser resources.

      Updating the application to generate HTTPS URLs directly is the recommended long-term solution.

    • 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.
    • 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.
    • 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.

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.

Feedback