FAQ

Installation and startup

docker compose up reports required variable … is missing

A required setting is missing from .env. deploy.sh generates all of them. For a manual install, compare against the Configuration reference; RST_USER_DB_PASSWORD, CADDY_SITE_ADDRESS and QRADAR_SEC_TOKEN are the usual gaps.

deploy.sh stops because images are missing

An image the compose file uses is not on the host. The archive carries the gateway, Caddy and PostgreSQL images; if one is missing, download the archive again and verify its SHA-256. An SSO deployment also needs the oauth2-proxy image; see SSO.

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

Run docker compose -f docker-compose.prod.yml logs caddy gateway. There are two common causes: port 443 is not open (on a cloud host, allow it in the security group), or CADDY_SITE_ADDRESS is a bare IP and the HTTPS handshake fails; use a hostname and a hosts entry.

A setting written to .env has no effect

In 1.0.1 and earlier, a standard install passes only the settings listed in docker-compose.prod.yml to the gateway, so settings such as RST_OUTPUT_LANG and RST_PLATFORM_* have no effect. Upgrade to 1.0.2 or later. On other versions, run docker compose -f docker-compose.prod.yml up -d after editing .env to recreate the container.

The gateway log shows /app/state is not writable by uid 10001

The state volume is not owned by uid 10001, and the entrypoint could not fix it. Run docker run --rm -v <volume>:/s alpine chown -R 10001:10001 /s, then restart the gateway.

QRadar connection

readyz returns 503

The qradar field gives the reason. not_configured means no Console has been entered. Any other value is the error from connecting to the Console: check QRADAR_URL, connectivity from the gateway host to the Console on 443, and whether the SEC token has expired. If certificate verification is on and the Console uses a private CA, put the CA in ./certs/ and set RST_QRADAR_CA_CERT.

"QRadar authentication failed. Check that the SEC token is valid and not expired."

The token is invalid or expired, or the authorized service was disabled. Generate a new token under Admin > Authorized Services in the Console and replace it in Settings.

The connection test passes but says the token cannot reach some APIs

The token's user role lacks the matching permission (Ariel, Offenses, rules or log sources). Change the user role as described in QRadar token permissions, run Deploy Changes, and test again.

"The token's security profile cannot access this API: …"

The error code is qradar_forbidden. Usually the user role lacks Ariel; the security profile may also not cover the log source in question. Fix it as above.

Sign-in

"This deployment still uses the shipped default password, so remote sign-in is refused."

RST_ADMIN_PASSWORD_HASH is not set. deploy.sh sets it; for a manual install, see Installing from the archive. An isolated test environment can set RST_ALLOW_DEFAULT_PASSWORD=1.

RST_ADMIN_PASSWORD_HASH is set but sign-in is still refused

Compose expanded the $ characters in the hash as variables. Write every $ in .env as $$.

The Users page says there is no separate user table

RST_USER_DB_URL is not configured. deploy.sh configures it and starts the account database; for a manual install, see Users.

After a role change, the user still acts with the old role

A role change applies at once but does not end the user's session; the interface updates when they reload the page. To sign them out immediately, select Disable.

Ask AI

A query returns zero rows

Ariel returns nothing for log sources the token cannot see, and reports no error, so zero rows can mean no data or no access. First select Ask again over the last 7 days, then open the AQL and check that the names in LOGSOURCENAME() and QIDNAME() match the Console, and finally check the security profile and the log-source whitelist.

"Log source X is outside the whitelist (RST_LOG_SOURCE_WHITELIST = …)."

The AQL names a log source outside the whitelist. An administrator adds it under Log source whitelist in Settings. reason=unbounded means the whitelist expands to more than 50 log sources, the statement has a subquery, or the log-source catalog could not be read, so the gateway cannot scope the query; narrow the whitelist.

"QRadar rejected the AQL: …"

The text after the colon comes from the Console; a wrong column or function name is the usual cause. Open the AQL, select Edit and run it again, or rephrase the question.

"The QRadar search timed out (120s). …"

The Ariel search ran past RST_AQL_TIMEOUT_SECONDS and was cancelled. Narrow the time range, or name the log sources in the question so that Ariel scans less. Large sites can raise the value.

Questions about "today" or "yesterday" return nothing or are off by a day

RST_TIMEZONE is not set, so the gateway splits days in UTC. Set it to your offset, such as +08:00, and recreate the gateway container.

"The model thought for over 45s without starting an answer, so it was stopped."

The model endpoint is congested or a reasoning model is thinking too long. Set that provider's reasoning to off or low in AI settings. RST_LLM_FIRST_TOKEN_TIMEOUT_S sets the limit.

Offenses

The Offenses page stays empty

Check in order: QRadar is connected in Settings; Polling on is on under Sync settings; OPEN offenses exist within RST_OFFENSE_INGEST_LOOKBACK (7 days by default); Minimum magnitude is not set too high; the token's security profile covers the log sources and networks that raise the offenses. Search the gateway log for offense_ingest to see the sync.

An offense closed in the Console is still OPEN in the gateway

Status is refreshed by last_updated_time in the next sync cycle (30 seconds by default). With a large backlog, the gateway log shows offense_ingest_page_cap_reached; wait a few cycles.

"Updating the offense failed: …"

A close, note or assignment could not be written back. Usually the token lacks write access to Offenses, or someone else already closed the offense. The closing reasons come from the Console; reopen the details to refresh them and try again.

Triage says "Scoring did not complete"

Model scoring timed out or failed. Lower Maximum clusters sent to the model, raise the provider timeout to 300 seconds or more, or lower its reasoning to low.

Triage picks up only a few offenses

The default window is 1440 minutes, counted from each offense's start time. Raise the Time window (minutes), or check the sync lookback.

Licensing

Activation fails because the host seats are used up

All host seats of the license are in use. On the old host, select Deactivate this license under Deactivate, then activate on the new host.

Offline activation fails because the host does not match

The host fingerprint in the .lic file does not match this host: state/machine-id or state/server_guid was regenerated, or the file was issued for another host. Restore the original files from backup, or request a new file with this host's fingerprint.

"Cannot read this machine’s hardware identity"

The container cannot read the host fingerprint files. state/machine-id or state/server_guid is missing (Docker then mounts a directory in its place), or its mode is not 644. Regenerate them as in Installing from the archive and restart.

The license is activated but the paid engines stay locked

An online license receives the engine keys after its first successful heartbeat; check the last heartbeat on the License page. For an offline license, confirm that the .lic file was issued for RST AI Copilot for QRadar; RST AI Copilot for Elastic licenses do not work here.

The license state is Heartbeat lost

An online license has not reached the license server for more than 7 days, and the paid engines and queries are locked. Check outbound access from the gateway host to license.reallysec.com:443; the next successful heartbeat clears the state.

Outbound channels

An email destination stays at Will retry or Given up

Check Last error in the Delivery log. Common causes are a missing mail server, a wrong password or a blocked SMTP port. Fix it and select Resend.

A destination shows Secret invalid

After the gateway is reinstalled, the old ciphertext cannot be opened. Edit the destination and enter the webhook URL and secret again.

Updates

Problems after an update

Run ./deploy/rst-update.sh --rollback to return to the previous version, or set GATEWAY_IMAGE_TAG back to the previous version and restart.

Contact support

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