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.
The gateway reaches Zabbix with one API token (or a user name and password). Two layers decide what it can see. The host permissions of the user group limit the host groups, so hosts, problems and history outside them cannot be queried. The user role sets the user type, whether API access is allowed, and actions such as acknowledging problems and running scripts. The gateway never loosens either layer.
The gateway is read-only by default. Only four kinds of action write to Zabbix: acknowledging or closing problems, creating triggers, creating maintenance windows, and running the Ping and Traceroute global scripts. A person starts each one in the UI. If you do not need them, a read-only account is enough.
For host groups the user group does not grant, the Zabbix API simply returns no data, without a permission error. When a query comes back empty, check this layer first.
API methods the gateway calls
| Feature | Methods | Zabbix requirement |
|---|---|---|
| Connection and version detection | apiinfo.version | None. Used by readyz and the connection test |
| Ask AI, live problems, posture, investigation, reports | problem.get, event.get, trigger.get, item.get, history.get, trend.get, host.get, hostgroup.get | Read permission on the relevant host groups |
| Item dictionary, monitoring health, device inventory, topology | item.get, host.get, template.get, discoveryrule.get, httptest.get, map.get | Read permission on the relevant host groups |
| SLA reports | service.get, sla.get, sla.getsli | Able to read the services and SLAs |
| Platform checkup | proxy.get, hanode.get, and the internal items of the Zabbix server host | Read permission on the host that monitors the Zabbix server itself (named Zabbix server by default). hanode.get is open to Super admin only; for other accounts the HA-node check shows as not checkable and the rest still runs |
| Acknowledge or close problems, add comments | event.acknowledge | The Acknowledge problems, Close problems and Add problem comments actions in the user role. Closing also requires the trigger to allow manual close |
| Create triggers | trigger.create | Admin user type and read-write permission on the target host's group. Triggers are created disabled |
| Maintenance windows | maintenance.get, maintenance.create, maintenance.delete | Admin user type, read-write permission on the target host groups, and the Create and edit maintenance action in the user role. The gateway only deletes maintenance windows it created |
| Remote ping and traceroute | script.get, script.execute | The Execute scripts action in the user role, plus the global script's own permission settings for this account and host |
Permission and menu names follow the UI of your Zabbix version. On the gateway side the write actions in this table are also subject to product roles; an administrator can switch them off for analysts and viewers under Permissions in Settings.
Create a dedicated account
Prerequisites
- Sign in to the Zabbix frontend as a Super admin.
Steps
- Under Users > User groups, create a user group such as
rst-copilot. In its host permissions, grant Read on the host groups to query and Read-write on the host groups where triggers or maintenance windows will be created. The platform checkup also needs read permission on theZabbix serversgroup. - Under Users > User roles, create a user role such as
rst-copilot:- Read-only: user type User.
- To create triggers or maintenance windows: user type Admin.
- Enable API access.
- Under actions, enable only what you need: Acknowledge problems, Close problems, Add problem comments, Create and edit maintenance, Execute scripts.
- Under Users > Users, create a user such as
rst-copilotin that user group with that role. - Create an API token for this user, set an expiry that fits your security policy, and copy the token. On Zabbix 6.0 this is under Administration > General > API tokens; from 6.4 on it is under Users > API tokens.
- Put the token in
ZABBIX_TOKENin.envand rundocker compose -f docker-compose.prod.yml up -d. On a first install, just enter it whendeploy.shasks for the Zabbix API token.
Do not use a Super admin's token. When the token expires, readyz returns 503 and queries fail with a Zabbix authentication error; create a new token with steps 4 and 5.
Without an API token you can use a user name and password (ZABBIX_USER, ZABBIX_PASSWORD); the gateway calls user.login to get a session. A token is recommended because password policies and lockouts after failed sign-ins do not affect it.
Scripts for remote diagnostics
Remote ping and traceroute never run arbitrary commands. They only call two Zabbix global scripts by name, Ping and Traceroute by default (both ship with Zabbix). The scripts must:
- Run on the Zabbix server or a proxy. Scripts that run on the agent are refused.
- Have the scope Manual host action.
- Allow the gateway account to run them on the target host through the script's user group and host permission settings.
Every run shows a preview first and calls script.execute only after confirmation; previews, runs and failures are all audited. To use other script names, set RST_DIAG_SCRIPT_PING and RST_DIAG_SCRIPT_TRACEROUTE. See Configuration reference.
Verify the permissions
In Settings, under Zabbix connection, select Test connection. On success it shows "Connected · Zabbix" with the version; on failure it shows "Unreachable" with the reason. You can also try a different URL and token there first; the active configuration still comes from .env and needs a gateway restart after a change.
You can also run curl -k https://<hostname>/readyz on the gateway host. zabbix set to ok means the token works and Zabbix is reachable.
Host group allowlist
The Zabbix user group decides what the gateway can read; the host group allowlist decides what it will read. Set the allowlist under Data scope and masking in Settings, or with RST_INDEX_WHITELIST in .env: comma-separated, * allowed, empty for no limit. When both are set, grant only the needed host groups in the user group and narrow them further with the allowlist.
With an allowlist set:
- Queries against host groups outside it are refused; reading an object outside it behaves as if the object does not exist, so its existence is not revealed.
- The model only sees host groups inside the allowlist.
- Problems pushed by a Zabbix webhook from outside the allowlist are dropped, and the intake status shows the number dropped.
- Polling for live problems needs
RST_ALERT_INGEST_GROUPSto name the host groups to poll. See Configuration reference.
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.
SSO
Users sign in with their corporate accounts. Caddy connects to your IdP through oauth2-proxy, roles come from IdP groups, and the audit log records each person. Enterprise feature.