Installation guide

1. Check the host

Use Linux with systemd on x86_64 for the published release. You need root installation access, curl, OpenSSL with Ed25519 support, Python 3.11+ for TOML inspection, tar, and standard system-user tools. A recovery console is recommended before enabling firewall response. No Rust toolchain or source checkout is needed for customer installation.

uname -srm
cat /etc/os-release
command -v curl openssl python3 systemctl
openssl version
python3 --version

2. Download and inspect the installer

The installer downloads a compiled .tgz release. It verifies an embedded Ed25519 public key against the signed manifest, then verifies the archive SHA-256 before extracting the permitted files. The archive contains the executable, configuration, service units, notices, and operator information; no Rust or API source.

curl -fsSL https://bhim.si/install.sh -o /tmp/bhim-install.sh
less /tmp/bhim-install.sh
sudo bash /tmp/bhim-install.sh

3. Start with monitoring

The licensed 0.4.1 profile starts with automatic response disabled. Review /etc/bhim-protection/config.toml, source permissions, management addresses, and your traffic path before enabling blocking. Existing configurations are preserved rather than reset.

sudo bhimkvh config-show
sudoedit /etc/bhim-protection/config.toml

Configuration reference License lifecycle

4. Activate this machine

The installer prompts for your key after installing the verified binary. If you install without a terminal or need to activate later, run the command below. Successful activation obtains a signed machine-bound lease and starts the license gate, response helper, and monitor.

sudo bhimkvh license activate
sudo bhimkvh license status
sudo -u bhim bhimkvh health --strict

5. Verify operation

Inspect both service status and health reasons. Establish a file-integrity baseline only after reviewing the files as trusted. Evidence queries should normally run as the bhim service user.

sudo systemctl status bhim-license.service bhim-response.service bhim-agent.service
sudo -u bhim bhimkvh metrics
sudo -u bhim bhimkvh incidents --limit 20
sudo bhimkvh baseline
sudo -u bhim bhimkvh verify

6. Renewal and offline operation

A systemd timer renews the lease hourly using this machine’s private device key. The raw license key is not required again. The default offline lease lasts at most the remaining paid license validity and never extends beyond the paid expiry date.

sudo systemctl status bhim-license-renew.timer
sudo bhimkvh license renew
sudo bhimkvh license check

7. Service operations

The monitor, response helper, and any gated optional collector are bound to the license gate. After changing protected policy, restart the helper and then the monitor. Correct time synchronisation matters for signed expiry checks.

sudo systemctl restart bhim-response.service
sudo systemctl restart bhim-agent.service
sudo -u bhim bhimkvh health --strict
sudo journalctl -u bhim-license.service -u bhim-agent.service -n 80 --no-pager

8. Migrate an existing installation

The binary installer preserves existing configuration and refuses to invent missing split-executor settings. Review and back up the current policy first. The bhim account is created before the migration check, so use id bhim to obtain the real numeric IDs. Set executor_socket, executor_uid, and executor_gid in the existing [blocking] section; keep response disabled while validating the migration.

id bhim
sudo cp -p /etc/bhim-protection/config.toml /etc/bhim-protection/config.toml.before-license
sudoedit /etc/bhim-protection/config.toml
# In the existing [blocking] section:
# executor_socket = "/run/bhim-protection/response.sock"
# executor_uid = ACTUAL_NUMERIC_BHIM_UID
# executor_gid = ACTUAL_NUMERIC_BHIM_GID

sudo chown root:bhim /etc/bhim-protection/config.toml
sudo chmod 0640 /etc/bhim-protection/config.toml
sudo bash /tmp/bhim-install.sh

9. Configure HTTP protection

The binary installer does not inject web-server configuration. Choose actual access-log paths and configure native ingress limits for your topology. Forwarded clients are not direct firewall peers.

Nginx and proxy setup

10. Upgrade a licensed host

Use the signed installer again. It verifies the new release, preserves a configuration backup and the previous binary, and retains existing evidence. A currently valid local lease can start the new services; otherwise activation is required.

curl -fsSL https://bhim.si/install.sh -o /tmp/bhim-install.sh
sudo bash /tmp/bhim-install.sh
sudo bhimkvh license status
sudo -u bhim bhimkvh health --strict

11. Stop protection and preserve evidence

Stop and disable the product units and renewal timer. Explicitly unblock addresses that should not remain blocked; permanent firewall entries are not automatically erased at license expiry or removal. Configuration, licensing identity, state, and logs remain for review or reinstallation.

sudo systemctl disable --now bhim-agent.service bhim-response.service bhim-kernel.service bhim-license.service bhim-license-renew.timer
# Emergency root unblocking is available even after expiry:
sudo bhimkvh unblock 192.0.2.10 --scope ssh