Windows

BotStopper supports Windows as a native system service. Download the Windows MSI for your architecture from the BotStopper releases. The repository requires access to the BotStopper project. Windows packages target amd64 (x64) and arm64 (AArch64).

Run the installer with administrator privileges. By default, it installs to C:\Program Files\Techaro\BotStopper and registers the BotStopper service. The executable is bin\botstopper.exe within that directory.

First-time setup

A new installation leaves the service stopped and sets its startup type to manual. Configure BotStopper before you start it.

The installer creates live configuration in %ProgramData%\Techaro\BotStopper, usually C:\ProgramData\Techaro\BotStopper:

Edit botstopper.env to set the listening address and the application that BotStopper protects:

BIND=:8923
TARGET=http://localhost:3923

Set TARGET to your application's address. The installer sets POLICY_FNAME to the live botstopper.yaml file. See configuration and policy configuration for the available configuration.

Persistent signing key

Set ED25519_PRIVATE_KEY_HEX to a random 32-byte Ed25519 seed, encoded as exactly 64 hexadecimal characters. Without this value, BotStopper generates a new key on every start and invalidates existing challenges and authentication cookies.

Generate the seed with PowerShell 7:

[Convert]::ToHexString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).ToLowerInvariant()

For Windows PowerShell 5.1, use:

$bytes = New-Object byte[] 32
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
try {
    $rng.GetBytes($bytes)
    [System.BitConverter]::ToString($bytes).Replace('-', '').ToLowerInvariant()
} finally {
    $rng.Dispose()
}

Set ED25519_PRIVATE_KEY_HEX in the service environment or in botstopper.env. Use the generated value, with no spaces or separators.

The configuration directory inherits permissions from %ProgramData%. On a standard Windows installation, local users can read those files. For machines with multiple users, supply the signing key through the service environment instead of the file.

Start the service

After configuration, start BotStopper from an administrator PowerShell session:

Start-Service BotStopper

Enable startup at boot:

Set-Service BotStopper -StartupType Automatic

Choose an installation directory

Use the INSTALLDIR property to select a different location. Replace the example MSI filename with the downloaded file:

msiexec /i ".\techaro-botstopper-VERSION-windows-amd64.msi" INSTALLDIR="D:\BotStopper"

Changing INSTALLDIR does not change the live configuration directory. The service still reads %ProgramData%\Techaro\BotStopper.

Silent installation

Pass /qn to install without the graphical interface:

msiexec /i ".\techaro-botstopper-VERSION-windows-amd64.msi" /qn INSTALLDIR="D:\BotStopper"

Configure the service and its signing key before its first start.

Service account

The service runs as the Windows virtual account NT SERVICE\BotStopper. Windows creates the account with the service. It does not require a password.

The installer grants this account access to %ProgramData%\Techaro\BotStopper. The service uses that access to read configuration and write logs. Preserve this access when you change directory permissions.

Logging

BotStopper writes logs to files instead of the Windows Event Viewer. The default files are in %ProgramData%\Techaro\BotStopper:

If the installer cannot write its bootstrap log to that directory, it tries the Windows temporary directory.

The default logging configuration keeps three backups, rotates at 100 MiB or seven days, and compresses old logs. See logging configuration to change these values.

Upgrades

Install the newer MSI over the existing installation. The installer replaces the service and starts the replacement during an upgrade. This interrupts traffic while it stops and replaces the service. Existing live configuration files remain intact.

The installer resets the startup type to manual. After an upgrade, restore startup at boot:

Set-Service BotStopper -StartupType Automatic

IIS

The Anubis on IIS guide describes the upstream reverse proxy integration. For BotStopper, use the BotStopper service, botstopper.exe, and the BotStopper configuration paths described here. See subrequest authentication for another proxy integration approach.