FAQ

Install and start

deploy.sh fails, docker compose up says required variable … is missing A required key is missing from .env. deploy.sh generates all of them; for a manual install fill them from the configuration reference, especially RST_USER_DB_PASSWORD, CADDY_SITE_ADDRESS, QRADAR_SEC_TOKEN.

https://<hostname>/v2/ does not open docker compose -f docker-compose.prod.yml logs caddy gateway. Usually: 443 not open (security group on cloud hosts), or CADDY_SITE_ADDRESS is a bare IP (TLS handshake fails; use a hostname + hosts entry).

Gateway log says /app/state is not writable by uid 10001 An older state volume was created by root. docker run --rm -v <volume>:/s alpine chown -R 10001:10001 /s, then restart the gateway.

QRadar connection

readyz returns 503 The qradar field is the reason. not_configured: no Console yet; with a 401: token invalid, expired or the authorized service disabled; a connection error: wrong QRADAR_URL, 443 blocked, or verification on with a private-CA Console and no RST_QRADAR_CA_CERT.

"Test connection" passes but one family shows unreachable The token's role lacks that family (Ariel / Offenses / rules / log sources), see Token permissions. Deploy Changes after editing the role.

Queries fail with qradar_forbidden Same cause, usually Ariel rights; or the security profile does not cover the target log source.

Certificate errors from the Console Verification is off by default; if RST_QRADAR_VERIFY_CERTS=true was set by hand on a self-signed Console, turn it off or put the CA in ./certs/ and set RST_QRADAR_CA_CERT.

Login

"This deployment still uses the factory password; remote login refused" RST_ADMIN_PASSWORD_HASH is unset. deploy.sh sets it; for manual installs see Installing from the archive. Isolated trials may use RST_ALLOW_DEFAULT_PASSWORD=1.

RST_ADMIN_PASSWORD_HASH is set and login still fails Compose swallowed the $ in the hash. Write every $ in .env as $$.

Users page says accounts cannot be added RST_USER_DB_URL is unset. deploy.sh configures it and starts userdb; for manual installs see Users.

Changed a role / disabled an account, the person is still working Disabling kicks sessions at once; a role change applies at once without kicking. They see it on the next page load.

Ask AI

Empty results Ariel silently omits log sources the token cannot see, so zero rows cannot tell "no data" from "no access". Click "Widen to the last 7 days and ask again"; then open the AQL and check that the LOGSOURCENAME() / QIDNAME() literals match the Console; then check whether the security profile and whitelist cover the target source.

"Log source X is not whitelisted" Add it in Settings or ask an admin. reason=unbounded means the whitelist expands past 50 names, the statement has a subselect, or the catalogue is unavailable, so the gateway could not scope it; write LOGSOURCENAME(logsourceid) IN (...) in the AQL yourself.

QRadar rejected the AQL (qradar_aql_error) params.reason is the Console's own message, usually a misspelt column or a misused function. Click "Let AI repair with the error", or open the AQL and edit.

Ariel search timed out RST_AQL_TIMEOUT_SECONDS defaults to 120. Narrow the window, add a LOGSOURCENAME() condition so Ariel scans less, or raise it on a large site.

"today / yesterday" comes back empty or one day off RST_TIMEZONE is unset and the gateway cuts days at UTC. Set your offset, e.g. +08:00.

First-token timeout, nothing for 45 s Model-side congestion or a reasoning model thinking too long. In AI settings set this provider's reasoning effort to "Off" or "Low", or add a fallback provider. RST_LLM_FIRST_TOKEN_TIMEOUT_S adjusts the cap.

The same question gives a different answer the second time A follow-up in the same conversation carries the previous context (source, references). For a clean re-ask, start a new conversation.

Offenses

The Offenses page stays at 0 In order: is QRadar connected in Settings; does the token's security profile cover any log source / network with offenses; is anything OPEN within RST_OFFENSE_INGEST_LOOKBACK (7 days); is RST_OFFENSE_MIN_MAGNITUDE set too high; is polling off in sync settings. Search the gateway log for offense_ingest.

An offense closed in the Console is still OPEN in the gateway Status refresh follows the last_updated_time cursor and lands within the next poll (30 s). With a big backlog the log shows offense_ingest_page_cap_reached; wait a few more ticks.

Closing an offense fails (offense_update_failed) The token lacks offense write rights; or someone closed it first; or the closing-reason id no longer exists (the list comes from the Console; reopen the drawer to refresh).

Triage shows "AI scoring incomplete" Model timeout. Lower "clusters sent for scoring" (10 works), raise the provider timeout to 300+, or set reasoning effort to "Low".

Triage pulls only a few offenses The default window is 60 minutes by offense start_time. Raise it (up to 7 days = 10080).

Licence

"activation limit reached" This licence's host seats are used up. "Deactivate this licence" on the old host, then activate.

"Offline license is bound to a different host" The fingerprint in .lic does not match this host: state/machine-id / state/server_guid were regenerated, or the file was issued for another machine.

"Cannot read the hardware identifier" /etc/machine-id is unreadable inside the container: state/machine-id is not mounted (docker mounts a directory when the file is missing) or is not mode 644.

Activated, but the four paid features stay locked Online licence: wait for the first successful heartbeat (within 5 minutes) and check "last heartbeat" on the License page. Offline licence: make sure the .lic was issued for rst_qradar_ai_copilot; an Elastic AI Copilot licence does not carry over.

State "grace period" / "heartbeat lost" The gateway cannot reach license.reallysec.com:443. Check outbound access; past the grace period the licence lapses.

Notifications

A mail target stays "retrying" / "given up" Check the last error in the delivery log. Usually no mail server configured, wrong password, or SMTP port blocked. Fix and "Retry".

A Feishu target shows "secret invalid" After a gateway reinstall the old ciphertext cannot be opened. Edit the target and re-enter the webhook and secret.

Upgrade

Reports show "legacy format" after an upgrade Old structure; regenerate.

Things break after an update ./deploy/rst-update.sh --rollback, or set GATEWAY_IMAGE_TAG back to the previous version and restart.

Still stuck

docker compose -f docker-compose.prod.yml logs --since 30m gateway > gateway.log, and send it with the readyz output to support@reallysec.com. The log contains neither your event data nor the token.