Native packages

Download the package for your operating system and architecture from the BotStopper releases. The repository requires access to the BotStopper release artifacts. Replace the example filenames with the filenames you downloaded.

BotStopper's package name is techaro-botstopper. Linux packages install the binary at /usr/bin/botstopper and configuration under /etc/techaro-botstopper.

Debian and Ubuntu

Install the Debian package with apt:

sudo apt install ./techaro-botstopper-VERSION-ARCH.deb

Red Hat and related distributions

Install the RPM package with dnf:

sudo dnf install ./techaro-botstopper-VERSION.ARCH.rpm

For systems that use yum:

sudo yum install ./techaro-botstopper-VERSION.ARCH.rpm

You can also install the package directly with rpm:

sudo rpm -ivh ./techaro-botstopper-VERSION.ARCH.rpm

Linux tarball

Extract the archive and enter its directory:

tar zxf ./techaro-botstopper-VERSION-linux-ARCH.tar.gz
cd techaro-botstopper-VERSION-linux-ARCH

Install the binary:

sudo install -Dm755 ./bin/botstopper /usr/local/bin/botstopper

Install the systemd unit with the binary path changed to /usr/local/bin/botstopper:

sed 's|/usr/bin/botstopper|/usr/local/bin/botstopper|' ./run/techaro-botstopper@.service \
  | sudo tee /etc/systemd/system/techaro-botstopper@.service >/dev/null
sudo systemctl daemon-reload

Install the default environment file:

sudo install -Dm644 ./run/default.env /etc/techaro-botstopper/default.env

Distribution packages

Some distributions package Anubis, the free, open source version of BotStopper. Those packages install Anubis. Use the BotStopper release package for BotStopper's additional features.

Configure an instance

Make a copy of the default environment file for each service you protect. This example protects a Gitea service:

sudo cp /etc/techaro-botstopper/default.env /etc/techaro-botstopper/gitea.env
sudo chmod 600 /etc/techaro-botstopper/gitea.env

For a Debian or RPM installation, copy the supplied policy file:

sudo cp /usr/share/doc/techaro-botstopper/botPolicies.yaml \
  /etc/techaro-botstopper/gitea.botPolicies.yaml

For a tarball installation, copy it from the extracted archive:

sudo cp ./doc/botPolicies.yaml /etc/techaro-botstopper/gitea.botPolicies.yaml

Edit /etc/techaro-botstopper/gitea.env for your application:

BIND=[::1]:8239
BIND_NETWORK=tcp
METRICS_BIND=[::1]:8240
METRICS_BIND_NETWORK=tcp
POLICY_FNAME=/etc/techaro-botstopper/gitea.botPolicies.yaml
TARGET=http://localhost:3000

Set TARGET to the application's address. Use policies and thresholds to select access rules and challenge difficulty.

For a signing key that remains stable across restarts, generate a random seed:

openssl rand -hex 32

Add ED25519_PRIVATE_KEY_HEX to the environment file with the generated value. Keep the signing key private. Replicas that share authorization cookies must use the same signing key.

Start the service

Enable and start the instance:

sudo systemctl enable --now techaro-botstopper@gitea.service

Inspect its state and logs:

sudo systemctl status techaro-botstopper@gitea.service
sudo journalctl -u techaro-botstopper@gitea.service

Fetch the metrics endpoint to confirm that the service responds:

curl 'http://[::1]:8240/metrics'

Configure your reverse proxy to send requests to BotStopper at port 8239. BotStopper forwards permitted requests to the application at TARGET. Preserve the client address as described in client IP headers.

• Apache
• Caddy
• Nginx
• HAProxy

For Windows service installation, use the Windows guide.