Getting Started

Blackwall's GateKeeper is a protective reverse proxy built around Blackwall bot and hacker detection technology. The core of the product is the Nginx web server, which proxies requests from the public web to your origin server, helping to protect it from bots, hacker attacks, and other unwanted traffic.

GateKeeper uses a customised Nginx build that provides the following additional features:

Blackwall Nginx module
HTTP/3 (QUIC)
OpenSSL 3.0
TLS 1.3
Brotli compression
SSL management (e.g. Let’s Encrypt)
Content caching
L7 DDoS protection
Client rate limiting

After installing GateKeeper, you must provision the Master Account API key directly in Redis before configuring your websites.

Step 1 - Install GateKeeper

As a prerequisite to installing Blackwall's GateKeeper, you must have a clean installation of Debian 12. Upgrade to Debian 12 if you are currently using Debian 11. You must then add the recommended Blackwall GateKeeper Debian repository and install the required packages.

Need to install from the Early Access / Test repository?

For step-by-step instructions on this type of installation, see the FAQ entry How do I get Beta / Early-Access to GateKeeper?

Import the Blackwall package digital signature key by executing the following commands:

apt-get update && apt install -y sudo curl gpg ca-certificates lsb-release apt-utils apt-transport-https

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

Add the Blackwall production repository to your system repositories:

echo "deb [signed-by=/usr/share/keyrings/botguard.gpg] https://repo.botguard.net/debian $(lsb_release -cs) gatekeeper" | tee /etc/apt/sources.list.d/botguard-gatekeeper.list

3. Update the package index:

apt update

Install the latest available version of Blackwall GateKeeper:
```
apt install botguard-gatekeeper
```
Reboot the server to apply the operating system changes:
```
reboot
```

Step 2 - Configure the Master Account API key

The Master Account API key associates the GateKeeper instance with your Blackwall account. You must provision the key directly in the GateKeeper Redis database. You can use these steps both to set the API key for the first time and to rotate an existing key.

Protect your API key

Your API key grants access to your Blackwall account and website data. Treat it as securely as a password. Do not expose it in documentation, shell history, logs, support requests, or other publicly accessible locations.

Obtain your Master Account API key from your Blackwall dashboard.

For more information, see Blackwall account credentials.
Connect to the GateKeeper server through SSH:
```
ssh <username>@<gatekeeper-server-ip>
```
Replace:
- <username> with the administrative user for the server.
- <gatekeeper-server-ip> with the IP address or hostname of the GateKeeper instance.
Set or update the API key in the Redis settings hash:
```
redis-cli HSET settings api-key "07e99282-f6a1-4aa7-97e4-9a065ba843db"
```
Replace the example value above with your Master Account API key.

The API key must use UUID format:
```
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
A successful command normally returns:
```
(integer) 1
```
If the api-key field already exists and its value is updated, Redis normally returns:
```
(integer) 0
```
Verify that the API key has been written correctly:
```
redis-cli HGET settings api-key
```
Redis should return the configured API key:
```
"07e99282-f6a1-4aa7-97e4-9a065ba843db"
```
Confirm that the returned value matches the API key from your Blackwall account.

Rotating the API key

To rotate the Master Account API key, repeat the HSET command with the new UUID value, and then use the HGET command to verify it.

Step 3 - Configure GateKeeper

Domain validation

When adding a website through the API or in the user interface (UI), BotGuard now validates the domain to ensure that it is active and resolvable. Attempting to add a non-existent domain will result in an error. Additionally, DNS records must be updated to verify domain ownership. Anyone who has the API key can add any website to their account, but nothing happens until the domain owner changes the DNS values. This approach aligns with industry practices, as domain validation is essential to confirm ownership and functionality before proceeding.

To proceed with domain setup, refer to Adding a Domain documentation.

Additional Information

SSL Certificates - Blackwall GateKeeper takes care of your website SSL certificate. It will issue a new certificate upon changing the DNS record, or you could upload your own certificate. Blackwall GateKeeper supports Let’s Encrypt as a SSL certificate vendors. It also might enable HTTP/3 (QUIC) protocol with TLS 1.3 encryption and optimized security settings, which will help you get A+ score with Qualys SSL Labs online test.
L7 DDoS Protection:
- Basic Protection - Mitigate DDoS attacks or server overuse by limiting the number of simultaneous connections and rate of requests.
- Advanced Protection - A visitor that triggered any of the protection rules from your site settings will be added to the blacklist at server firewall for 1 hour and, hence, unable to send any new requests to the server.
  - List blocked IP addresses:
    IPv4IPv6
    ipset list blackhole4
    
    ipset list blackhole6
  - Add IP address to blacklist:
    IPv4IPv6
    ipset add blackhole4 1.2.3.4
    
    ipset add blackhole6 1ce:1ce:babe
  - Remove IP address from blacklist
    IPv4IPv6
    ipset del blackhole4 1.2.3.4
    
    ipset del blackhole6 1ce:1ce:babe
Advanced Firewall Setup - Firewall settings block packets sent from private IPv4 subnets by default. However, such networks are used by the cloud providers infrastructure sometimes. The file /etc/iptables/rules.v4 already contains the rules to ignore some subnets when using certain cloud services. You might need to adjust these settings when using custom VPC networks.

Feedback