Configuration reference
Settings in the .env file of the install directory: required settings, sign-in and accounts, Zabbix connection and data scope, content packs and online update, live problems, models, reports and inspections, platform checkup and remote diagnostics, audit and retention, resources.
Configuration lives in .env in the install directory, and every key in it reaches the gateway container. After a change, run docker compose -f docker-compose.prod.yml up -d; the change applies once the gateway container is recreated. Settings not listed here can keep their defaults; .env.example in the archive documents every setting.
Settings you can change in Settings (host group allowlist, field masking, audit and forwarding, role permissions, separation of duties) are saved in settings.yml on the gateway_state volume and take precedence over .env. Providers in AI settings are saved in llm_providers.yml on the same volume. The matching .env entries only seed the first start.
Write every $ in a .env value as $$, for example in a password hash.
Required
| Setting | Description |
|---|---|
ZABBIX_URL | Zabbix JSON-RPC URL, ending in /api_jsonrpc.php |
ZABBIX_TOKEN | Zabbix API token; see Zabbix permissions. ZABBIX_USER and ZABBIX_PASSWORD can be used instead |
LLM_API_KEY, LLM_MODEL | API key and model name of the first LLM provider |
CADDY_SITE_ADDRESS | Hostname or IP users open; several can be given, separated by spaces |
RST_GATEWAY_SHARED_SECRET | Shared secret between Caddy and the gateway; Caddy injects it into every request. Generated by deploy.sh |
RST_ADMIN_TOKEN | Operations API token, sent in the X-RST-Admin-Token header. Generated by deploy.sh |
RST_ADMIN_PASSWORD_HASH | Password hash of the administrator admin, generated by deploy.sh from the password entered during installation |
Sign-in and accounts
Accounts are managed on the Users page, with the roles administrator, analyst and viewer, plus auditor on Enterprise. With SSO on, the IdP manages accounts instead; see SSO.
| Setting | Default | Description |
|---|---|---|
RST_ADMIN_USERNAME | admin | Name of the first administrator |
RST_ADMIN_PASSWORD_HASH | Written by deploy.sh | Password hash of the administrator admin, with every $ written as $$. To generate it by hand: docker run --rm rst-ai-copilot-for-zabbix-gateway:<version> python -m backend.session_auth '<password>', or docker exec rst-ai-copilot-for-zabbix-gateway python -m backend.session_auth '<password>' while the gateway runs. When empty, the factory password Admin@123 applies and only works from the gateway host itself. It is used only when the account is first created, or applied while admin still has the factory password; changing it later does not change admin's password, so a forgotten password is reset by another administrator on the Users page |
RST_ALLOW_DEFAULT_PASSWORD | Empty | 1 allows signing in with the factory password over the network; for isolated test setups only |
RST_SESSION_TTL_HOURS | 12 | Sign-in session lifetime in hours |
RST_TRUSTED_PROXIES | 127.0.0.0/8,::1/128,172.16.0.0/12 | Trusted proxies. Forwarded and SSO identity headers are honored only from these addresses. Add Caddy's address if it is outside the Docker default networks; do not add office networks |
RST_SEPARATION_OF_DUTIES | Empty | 1 turns separation of duties on and pins it, so it cannot be switched off in the UI. Enterprise |
RST_ROLE_OVERRIDES | Empty | Tighten role permissions, for example analyst:script.execute; removals only. Also editable under Permissions in Settings |
Zabbix connection and data scope
| Setting | Default | Description |
|---|---|---|
ZABBIX_USER, ZABBIX_PASSWORD | Empty | Account used when ZABBIX_TOKEN is empty |
ZABBIX_PUBLIC_URL | Empty | The Zabbix frontend address as the browser sees it, for "Open in Zabbix". When empty, the scheme, host and port of ZABBIX_URL are used |
RST_INDEX_WHITELIST | Empty | Host group allowlist, comma-separated, * allowed. Empty means no limit, which is only advisable for test setups |
RST_MASKING_MODE | Empty | Field masking: cloud, private or airgapped. When empty, the license decides |
Content packs and online update
| Setting | Default | Description |
|---|---|---|
RST_CONTENT_AUTO_APPLY | 1 | A new content pack (prompts and templates) found by an update check is activated right away. The gateway checks once a day, and an administrator can also check by hand. With 0 it is only downloaded, verified and kept; an administrator activates it under Settings > Content pack with Roll back to this version on that version |
RST_UPDATE_URL | https://github.com/reallysec/RST-AI-Copilot-for-Zabbix/releases | Source of the release manifest and content packs. An internal mirror must keep the GitHub Releases layout |
Live problems
| Setting | Default | Description |
|---|---|---|
RST_ALERT_INGEST_POLL | 1 | Poll Zabbix for problems. 0 turns it off |
RST_ALERT_INGEST_INTERVAL_SECONDS | 15 | Poll interval in seconds, at least 3 |
RST_ALERT_INGEST_GROUPS | Empty | Poll only these host groups, comma-separated; only groups inside the allowlist are used. When empty, all host groups are polled; but with a host group allowlist set, this must be filled in, otherwise nothing is polled and the Live problems page shows why |
RST_ALERT_INGEST_LOOKBACK | 1h | How far back the first poll reaches, in s, m, h, d or w, for example 24h or 7d |
RST_ALERT_SUMMARY | 1 | 0 stores problems without AI summaries |
RST_ALERT_SUMMARY_MIN_SEVERITY | warning | Summarize only problems at or above this severity, as a Zabbix severity name or 0 to 5 |
RST_ALERT_WEBHOOK_SECRET | Empty | Token checked on Zabbix webhook pushes. When empty, pushes are not accepted |
RST_CORRELATION_WINDOW_S, RST_CORRELATION_STORM_MIN_HOSTS | 600, 5 | Time window (seconds) and minimum host count of an alert storm |
A Zabbix webhook media type sends a POST to https://<hostname>/api/alerts/ingest with the header X-RST-Alert-Token set to the value of RST_ALERT_WEBHOOK_SECRET.
Models and reasoning
| Setting | Default | Description |
|---|---|---|
LLM_BASE_URL | https://ark.cn-beijing.volces.com/api/v3 | Endpoint of the first provider |
LLM_TIMEOUT_S | 180 | Timeout of one model call, in seconds |
RST_LLM_GENERATE_TIMEOUT_S | 45 | Timeout of the query-generation step in chat, in seconds |
RST_OUTPUT_LANG | zh | Output language of background work no user triggered (alert summaries, scheduled reports, scheduled inspections): zh or en. Output a user triggers follows that user's UI language |
RST_RATELIMIT_GENERATE, RST_RATELIMIT_EXECUTE | 30, 30 | Query generations and executions per minute, counted per user with SSO and per source IP otherwise. Raise them when many people share one egress IP |
RST_EMBED_MODEL, RST_EMBED_BASE_URL, RST_EMBED_API_KEY, RST_EMBED_DIM | Empty | Embedding endpoint for the knowledge base. Can also be set in AI settings |
Reports, inspections and monitoring health
| Setting | Default | Description |
|---|---|---|
RST_REPORT_SCHEDULE | Empty | Any of daily, weekly, monthly, comma-separated. When empty, nothing is generated automatically. Needs a paid license. When Schedule on the Outbound channels page has a period ticked, the page wins and this entry and RST_REPORT_TZ are ignored |
RST_REPORT_TZ | UTC | Time zone of report period boundaries |
RST_BASELINE_CRON | Empty | Schedule for the monitoring health check, as a 5-field crontab. When empty, it never runs on a schedule |
RST_PUBLIC_BASE_URL | Empty | Link back to this product in notifications, for example https://copilot.corp.local |
Platform checkup and remote diagnostics
| Setting | Default | Description |
|---|---|---|
RST_ZABBIX_SERVER_HOST | Zabbix server | Name of the host that monitors the Zabbix server itself. The platform checkup reads internal items from it |
RST_DIAG_SCRIPT_PING, RST_DIAG_SCRIPT_TRACEROUTE | Ping, Traceroute | Zabbix global script names used by remote diagnostics |
RST_DIAG_RPM | 5 | Remote diagnostics per user per minute |
Audit and retention
| Setting | Default | Description |
|---|---|---|
RST_AUDIT_ENABLED | true | Write the audit log to audit.db on the gateway_state volume |
RST_ALERTS_TTL_DAYS | 30 | Days to keep alert copies |
RST_ANALYSIS_TTL_DAYS | 30 | Days to keep analysis records |
RST_CONVERSATION_TTL_DAYS | 7 | Days of inactivity before a conversation expires |
RST_REPORT_RETENTION_DAYS | 90 | Days to keep reports |
Resources and version
| Setting | Default | Description |
|---|---|---|
RST_GATEWAY_CPUS, RST_GATEWAY_MEM | 2, 2g | CPU and memory cap of the gateway container |
GATEWAY_IMAGE_TAG | The version in the compose file | Gateway image version to run; written by rst-update.sh |
CADDY_DEFAULT_SNI | Same as CADDY_SITE_ADDRESS | Certificate name Caddy uses when the browser sends no SNI, for example when users open an IP address |
Caddy only terminates TLS and injects the shared secret. /healthz and /readyz need no sign-in; /metrics returns 404 from outside, and Prometheus scrapes gateway:8000/metrics inside the compose network.
For SSO settings, see SSO.
Installing from the archive
Install the gateway with one command or from a downloaded archive, install on an air-gapped host, answer the deploy.sh prompts, verify the install, and install without deploy.sh.
Zabbix permissions
Create a dedicated Zabbix account for the gateway. The user group decides which host groups are visible; the user role decides which API methods and actions are allowed. Includes the permissions each feature needs, a least-privilege setup, how to verify it, and the host group allowlist.