International setup

Use this guide for an English-speaking operator or a team working across time zones. The CLI help and diagnostic messages are in English; built-in notification text supports English and Simplified Chinese. 中文 · All commands

Choose your platform

Installation supplies the binary and a safe configuration. It does not start a new protection service automatically. Linux secure-ssh, keepalive and malware scanning are not available on Windows/macOS. See platform boundaries and platform-specific operations. If already root, omit sudo in the Linux examples.

First Linux deployment

Install the latest published stable release:

curl -fsSL https://raw.githubusercontent.com/neko233-com/banhack233/main/scripts/install.sh | sh
sudoedit /etc/banhack233/config.json

In the existing notifications object, set these fields; preserve its other fields:

{
  "language": "en",
  "timezone": "UTC"
}

This is a fragment, not a replacement configuration. The complete English Linux example has English notifications, UTC, disabled external channels, dry-run mode and no regional exceptions. On Windows/macOS, retain the paths generated by init-config instead of copying Linux paths.

Keep dry_run=true, check ssh_ports against your actual SSH listener, and add your office/VPN public egress IPv4 and IPv6 addresses to ignore_ips. The server sees the public egress address, not a private laptop address or MAC. Replace YOUR_PUBLIC_IP before running:

sudo banhack233 whitelist YOUR_PUBLIC_IP
sudo banhack233 config-check
sudo banhack233 notify-test -channel console
sudo banhack233 doctor
sudo banhack233 install-autostart
sudo systemctl status banhack233 --no-pager
sudo journalctl -u banhack233 -n 50 --no-pager

Use a single authoritative authentication log source; if your distribution only has journald, arrange an SSH text-log export first. Confirm the log cursor advances on real login events. Do not replay old logs against a production firewall or deliberately fail logins from your only recovery address. Isolated dry-run replay provides a safer acceptance test.

After observing the dry-run behavior and confirming a recovery login, enable enforcement:

sudo banhack233 enable-production
sudo systemctl restart banhack233
sudo banhack233 status
sudo banhack233 auto-update -enable
sudo banhack233 auto-update -status

Daily updates install verified stable releases and restart the managed service, retaining configuration, whitelists and state. Update and rollback details. Do not run a second SSH banning tool with conflicting rules unless you maintain matching exceptions there too.

Language and time zones

• notifications.language: en or zh-CN; omitted/empty retains Chinese for existing configurations.
• notifications.timezone: UTC, Local or an IANA name such as Europe/London, America/New_York or Asia/Shanghai. The bundled time-zone database supports minimal hosts and Windows; named zones account for daylight saving time.
• Each Telegram, Discord, Slack, Feishu/Lark, generic webhook and email target can override language; an omitted/empty channel value inherits the global setting.
• Built-in titles, labels, reasons, durations and test messages are translated. Custom rule names, custom test text, process details and GeoIP database values remain as supplied. location_language only controls an additional Chinese location row; it is separate from message language.
• Human-readable notification times include a numeric UTC offset. JSON timestamps identify the same instant in RFC 3339; Discord's machine timestamp remains UTC. This setting does not change log timestamps, ban duration, report file names, the OS clock or the daily updater schedule.

Mixed-language team example, merged into notifications:

{
  "language": "en",
  "timezone": "UTC",
  "feishu": {"language": "zh-CN", "location_language": "zh-CN"},
  "discord": {"language": "en"},
  "email": {"language": "en"}
}

For a new, absent configuration after downloading/building the binary:

sudo banhack233 init-config -language en -timezone UTC

It refuses to overwrite an existing file. Edit existing language fields instead; -force replaces the entire configuration. Run config-check and restart the daemon after edits. Language/time-zone options require v0.2.3 or later; older binaries reject these new fields.

Pick a notification channel

Notification setup covers credentials, service environment, retries, test commands and SMTP authentication limits. notify-test actually sends a message to each selected enabled destination. Leave channels disabled until their destination and credentials are configured.

Network access and offline installation

Install/update needs HTTPS access to GitHub, its API and redirected release-asset hosts. Notifications need access only to enabled providers. SSH detection and local firewall enforcement do not depend on those providers being reachable; failed notifications enter a bounded queue.

HTTP notifications and the Go updater use HTTPS_PROXY, HTTP_PROXY and NO_PROXY from their own process environment. For systemd, configure a private EnvironmentFile in a service drop-in. The protection service and banhack233-update.service are separate: configure both when both need a proxy. A shell export is not automatically inherited by systemd or a Windows SYSTEM task. SMTP uses direct TCP and does not use the HTTP proxy. Keep CA certificates and host time correct; do not disable certificate checks.

For a host without GitHub access, download the correct OS/architecture asset and SHA256SUMS.txt from the same published Release on a connected machine, then transfer both over a trusted connection. Example for Linux amd64, run in the download directory:

(
  set -eu
  test ! -e /usr/local/bin/banhack233
  test ! -e /etc/banhack233/config.json
  awk '$2 == "banhack233-linux-amd64" {print}' SHA256SUMS.txt > binary.sha256
  test "$(wc -l < binary.sha256)" -eq 1
  sha256sum -c binary.sha256
  chmod +x banhack233-linux-amd64
  ./banhack233-linux-amd64 version
  sudo install -m 755 banhack233-linux-amd64 /usr/local/bin/banhack233
  sudo banhack233 init-config -language en -timezone UTC
)

Run each step only after the previous one succeeds. This recipe is for a fresh installation; for an existing host use the backup and rollback procedure. On macOS use shasum -a 256; on Windows use Get-FileHash -Algorithm SHA256, compare the exact asset entry, and follow the platform paths. The checksum establishes integrity against the Release manifest; it is not an independent release signature. Automatic updates need working connectivity and can be disabled on an offline host.

Geography is optional

New default configurations use the same five-event threshold worldwide. region_rules is an explicit optional override; existing configured overrides are preserved. GeoIP is enrichment, not device identity or evidence that a person is malicious. A missing database uses the base threshold; IPv6 protection works without location lookup. No GeoIP download or external IP-location API is required to start protecting SSH. Whitelist known shared egress addresses instead of trusting an entire country.

Getting help

English issues are welcome. Include the release version, OS/architecture, command, expected behavior, exit status and redacted relevant logs. Never post a full configuration, environment dump, SSH password, token, webhook URL or private state file. Troubleshooting covers log sources, notification failures and recovery. Each HTML page links to its corresponding language, source tag and release; an offline HTML archive accompanies published releases.