FAQ

Installation and startup

install.sh reports Docker Engine 24+ is required or Docker Compose v2 is required

The host has no Docker, or only the old docker-compose. Install Docker Engine 24 or later and the Compose v2 plugin (docker compose version prints a version), then run the install command again. See Requirements.

install.sh reports openssl is required, run as root or run this from an interactive terminal

The installer verifies the release signature with openssl; install it as the message says. The script needs root, so run it as curl … | sudo bash. It ends by running deploy.sh, which asks questions, so it must run in an interactive terminal, not in CI or a remote command without a TTY.

install.sh prints "China mirror not configured yet (set RST_COS_BASE); skipping it"

This is expected. The China mirror (--mirror cn) is not available yet, so the script skips it and uses GitHub. If GitHub is unreachable too, the script reports could not download a signed release; retry later. If GitHub is too slow, run install.sh --download-only on a machine that can reach GitHub, copy the verified archive to the target host, unpack it and run ./deploy.sh.

install.sh reports release signature check FAILED or is not the signed release

The manifest or archive does not match Reallysec's signature. The script deleted the file and installed nothing. Do not bypass the check; retry from another network, and contact support if it still fails.

install.sh prints is not signed yet

The newest version was just published and its signed manifest is not uploaded yet. The script installs the newest signed version instead. Run it again a few minutes later to get the newest one.

https://<hostname>/v2/ does not open

Run docker compose -f docker-compose.prod.yml logs caddy gateway. Common causes: port 443 is not open (on a cloud host, allow it in the security group), or CADDY_SITE_ADDRESS is wrong.

The password is right, but sign-in says the username or password is wrong

Each $ in RST_ADMIN_PASSWORD_HASH in .env must be written as $$; otherwise compose treats the hash as variables. Fix it and run docker compose -f docker-compose.prod.yml up -d. A .env written by deploy.sh already does this.

Zabbix connection

readyz returns 503

/readyz contacts Zabbix on every call, and the zabbix field of the response gives the reason. Check ZABBIX_URL, the network path from the gateway host to Zabbix, and the API token or account. In Settings, Zabbix connection > Test connection shows the exact error.

"Cannot reach the Zabbix API. Check that Zabbix is up and ZABBIX_URL is correct."

Code zabbix_unreachable. The gateway cannot connect: wrong address or port, a firewall in the way, or the Zabbix frontend is down. With an https:// ZABBIX_URL the gateway verifies the certificate by default, so an untrusted certificate also fails here.

"This address is not a Zabbix API (it should end with /api_jsonrpc.php)."

The address answers, but not as Zabbix JSON-RPC. Set ZABBIX_URL to https://<Zabbix frontend>/api_jsonrpc.php.

"Zabbix API authentication failed. Check the API token or username / password."

The token expired, was deleted or disabled, or the username or password is wrong. Generate a new token under User settings > API tokens in Zabbix and replace it in Settings. For the rights the account needs, see Zabbix permissions.

"Zabbix X is not supported: 6.0 or later is required"

Code zabbix_version_unsupported. The gateway supports Zabbix 6.0 and later; 6.0, 6.4, 7.0, 7.2 and 7.4 are verified. Upgrade Zabbix 5.x or earlier first.

"The connection address changed, so re-enter the password / API key."

The Zabbix address was changed in Settings. Stored credentials are only sent to the original address, so enter the token or password again.

A query returns nothing

First confirm Zabbix has data for that period. Then check the Host group allowlist in Settings: host groups outside it are never queried. Finally check that the Zabbix API account's user group can read those host groups. Zabbix silently leaves out hosts the account cannot see.

"Index X is not in the configured whitelist"

Code index_not_whitelisted. The question touches a host group outside the host group allowlist. An administrator can add it to Host group allowlist in Settings.

Model calls

"The model call timed out"

Code llm_timeout. The model endpoint is busy or slow. Retry later, or raise the provider's timeout in AI settings.

"The model service is unavailable: none of the enabled providers succeeded."

Code llm_unavailable. Check the API key, model name and base URL in AI settings, and outbound access from the gateway host to the model endpoint. A fully offline site needs an OpenAI-compatible model service hosted on its own network.

Several providers are configured, but there is no switch to a backup when the first fails

Multi-provider failover is an Enterprise feature. Community and Professional use only the first enabled provider in the list.

"The AI request failed." or "The model returned something that could not be parsed."

Codes llm_request_failed and llm_unparseable. The provider's raw error goes to the server log only. Run docker compose -f docker-compose.prod.yml logs --since 30m gateway and search for llm_call_failed.

"Too many requests. Try again in about Ns."

Code rate_limited. AI endpoints such as query generation allow 30 requests per minute per source IP by default. Teams behind one egress IP hit it sooner.

License

Activation fails because the license server cannot be reached

Outbound access from the gateway host to license.reallysec.com:443 is blocked. Open it and retry. Hosts without internet access use offline activation; see License.

Activation fails because the license server refused it

The text after the colon is the server's reason. Usually the license has no host slots left: on the old host, open Deactivate and choose Deactivate this license, then activate on the new host. It can also mean state/machine-id was regenerated and the host fingerprint changed; restore the original file from backup, or contact us.

Activation fails because the license belongs to another product

The license was issued for another product. A license for RST AI Copilot for Elastic or QRadar does not work for Zabbix. Ask sales for a license for this product.

Offline activation says Enterprise is required

Offline activation takes an offline token issued for an Enterprise license. Professional licenses activate online.

"Cannot read this machine's hardware identity"

The container cannot read /etc/machine-id. Check that state/machine-id exists in the deployment directory and is mounted into the gateway container. Do not regenerate it: a new file means a new machine, and the current license stops working.

Activated, but a paid feature is still locked and asks for a license

Code feature_sealed. The core of Triggers & items ships encrypted in the image and needs the feature key in the license to unlock. An offline license issued without its feature key causes this; contact us to reissue it. For other locked features, check Unlocked features on the License page to confirm the edition.

License status is Heartbeat lost, Expired or Revoked

An online license that has not reached the license server for more than 7 days, a license more than 7 days past expiry, or a revoked license falls back to Community: free features keep working, paid features pause, and accounts and data are kept. For a lost heartbeat, restore access to license.reallysec.com:443 and it recovers on its own. For expiry or revocation, contact sales and activate the new license key.

License status is Invalid

The license failed verification: signature, product or host binding does not match. Every endpoint except sign-in, the license agreement and the License page is refused. Paste the license key bound to this host and activate again.

Sign-in and seats

Only administrators can sign in because enabled accounts exceed the licensed seats

Code seats_exceeded_admin_only. This only happens with multi-user password login turned on. More accounts are enabled than the license allows: 1 for Community, at most 10 for a trial, and the licensed user count for Professional and Enterprise. It usually follows an expired license or a switch to one with fewer users. An administrator signs in and disables extra accounts under Users, or renews or adds seats. No account or data is deleted.

Creating or enabling an account opens an upgrade dialog

Code users_need_professional (Community has one user) or user_seats_exhausted (all licensed seats are in use). Enabled accounts have reached the licensed user count. Disable an account, or activate a license with more users.

Remote sign-in is refused because the account still uses the factory password

.env has no RST_ADMIN_PASSWORD_HASH, so the admin account still has its factory password. This usually means a deployment upgraded from 2.0.0 (deploy.sh sets it on a new install). Run docker exec rst-ai-copilot-for-zabbix-gateway python -m backend.session_auth '<password>', put the output into RST_ADMIN_PASSWORD_HASH= in .env (write each $ as $$), then run docker compose -f docker-compose.prod.yml up -d. You can also sign in on the gateway host itself and change the password.

Sign-in is refused after too many failed attempts

10 failed attempts within 5 minutes from one source or for one account lock sign-in for a while. Wait 5 minutes and try again.

"Read and accept the End User License Agreement (EULA vX) to continue."

Code eula_not_accepted. This account has not accepted the current version of the agreement. Read it on the page that opens and accept.

Content packs

A content pack was not applied automatically

Check in this order:

1. Whether .env sets RST_CONTENT_AUTO_APPLY=0. With 0, a new pack is verified and stored on the host but does not take effect. An administrator finds that version under Content pack > Roll back in Settings and chooses Roll back to this version to make it active.
2. Whether an update check has run. New packs come with the online update check: the gateway checks once a day, and an administrator can choose Check now under Online update.
3. Whether the license was activated offline. Offline-activated installs never contact the update source; import a pack by pasting its signed token under Content pack > Import a content pack.

A pack with a bad signature or an older version is rejected with code content_pack_rejected.

Online update

Online update shows no new version

Check in this order:

1. Choose Check now. The gateway checks once a day on its own, so a version published since the last check may not show yet.
2. Whether the gateway host can reach github.com. A failed check is silent: the page keeps the last result or shows "Not checked". Search the gateway log for update_check_failed.
3. Whether the license was activated offline. Offline-activated installs do not contact the update source; upgrade with a new delivery bundle, see Upgrade and backup.
4. Whether the version was just published. It is not offered until its signed manifest is uploaded; check again in a few minutes.

It says "Staged", but the version has not changed

The gateway only downloads and verifies; the install happens on the host. Run sudo ./deploy/rst-update.sh in the deployment directory. It rolls back on its own if the health check fails.

Something breaks after an update

Run sudo ./deploy/rst-update.sh --rollback to return to the previous version, or set GATEWAY_IMAGE_TAG in .env back to the old version and run docker compose -f docker-compose.prod.yml up -d.

Contact support

Run docker compose -f docker-compose.prod.yml logs --since 30m gateway > gateway.log, and send gateway.log with the output of /readyz to support@reallysec.com.