Zabbix Frontend Module

Separately from self-monitoring, zabbix-module/seyalrun/ is a Zabbix frontend module that embeds SeyalRun directly into the Zabbix UI:

• A SeyalRun menu (right after Monitoring): Dashboard, Assets, SSH Hosts, Sessions, Jobs, Automation, and (Zabbix admins+) Trigger Bindings.
• A permission-aware SSH Hosts page — a terminal icon appears next to every Linux host the current Zabbix user can write to, and opens straight into SeyalRun's SSH terminal.
• A SeyalRun entry under Administration (super admins only) for SeyalRun's own settings (rate limits, session timeouts, Zabbix-module trust).

All communication is over SeyalRun's REST API — no shared database, no shared browser storage. Trust is anchored by one HMAC secret.

Requirements

• Zabbix 7.0 LTS or 8.0, frontend module support enabled (default since 6.4).
• A running SeyalRun deployment, reachable over HTTPS from wherever this Zabbix frontend's PHP runs (server-side curl call — doesn't need to be the same network the browser uses).
• PHP's curl extension (already required by Zabbix itself).

Install

1. Copy the module into Zabbix's modules folder — inside the frontend's own ui/modules/ directory, e.g. /usr/share/zabbix/ui/modules/ for a Debian/Ubuntu package install (dpkg -L zabbix-frontend-php | grep ui$ to confirm the exact path on your system; for the official Docker image it's /usr/share/zabbix/modules/):

   sudo cp -r zabbix-module/seyalrun /usr/share/zabbix/ui/modules/seyalrun
   sudo chown -R www-data:www-data /usr/share/zabbix/ui/modules/seyalrun

2. Configure it:

   cd /usr/share/zabbix/ui/modules/seyalrun
   sudo cp config.php.example config.php

   Edit config.php:

   return [
       'seyalrun_url' => 'https://seyalrun.example.com',        // reached by THIS SERVER
       'seyalrun_public_url' => 'https://seyalrun.example.com', // reached by the BROWSER
       'module_secret' => '<same value as ZABBIX_MODULE_SECRET below>',
       'verify_tls' => true,
   ];

   These two URLs are often the same but don't have to be — on a single test box it's common for seyalrun_url to be https://127.0.0.1:8443 (fine for this server's own curl calls) while seyalrun_public_url has to be the box's real IP/hostname, since that one ends up in the iframe/link URLs your browser actually loads. Getting this backwards is the #1 cause of a page that loads but renders blank.

3. Set the matching secret on the SeyalRun side, in SeyalRun's .env:

   ZABBIX_MODULE_SECRET=<openssl rand -hex 32>

   Restart identity-service (or the whole stack) to pick it up. Treat this secret like a password — never commit config.php.

4. Allow SeyalRun to be framed by this Zabbix's origin, in SeyalRun's .env:

   FRAME_ANCESTORS=https://zabbix.example.com

   Restart edge-proxy to pick it up.

5. Register and enable the module — either via Administration → General → Modules → Scan directory in the UI, then flip SeyalRun's status to Enabled; or via the module.create API call (useful for scripted installs) with relative_path set to modules/<dir-name> — root-relative to the frontend's own directory, not just the module's own folder name.

6. Refresh Zabbix — SeyalRun should appear in the left-hand menu, right after Monitoring, and (as a super admin) under Administration.

How the trust model works

Zabbix page load
  └─ PHP controller (server-side): reads the logged-in Zabbix user + type
       └─ HMAC-signs {username, zabbix_user_type} with module_secret
            └─ POST https://<seyalrun>/api/v1/auth/zbx-sso-init
                 header: X-Zabbix-Module-Signature: <hmac-sha256 hex>
       └─ SeyalRun verifies the signature, mints a 120-second one-time sso_code
  └─ page renders <iframe src="https://<seyalrun>/?sso_code=...#/<route>">
       └─ SeyalRun's frontend exchanges the code for a real session, embedded-mode UI

A fresh code is minted per page load (and per host row on the SSH Hosts page) — codes are single-use and cheap, so every page stays self-contained rather than depending on a shared, long-lived session.

Zabbix's own user-type maps straight onto SeyalRun's roles: Zabbix User → SeyalRun user, Admin → admin, Super Admin → superadmin.

SSH Hosts: visibility vs. access

The terminal icon's visibility is decided entirely by Zabbix's own host.get(editable: true) — Zabbix's host write permission for the current user. Clicking it still goes through SeyalRun's own SSO and then its own PAM authorization + credential gate — a user with Zabbix write access but no SeyalRun grant for that host gets a clear "request access" message, never a shell. Zabbix permissions never bypass SeyalRun's.

Uninstall

Disable the module under Administration → General → Modules, then remove the directory from Zabbix's modules/ folder. Nothing on the SeyalRun side needs cleanup beyond optionally clearing ZABBIX_MODULE_SECRET.

What's intentionally not here

• No shared database — all communication is the REST API over HTTPS.
• No secrets in Zabbix's own module-configuration UI — config.php is a plain file specifically so behavior doesn't depend on Zabbix-version-specific module-config storage.
• No bypass of SeyalRun's own access control — Zabbix permissions decide what's visible; SeyalRun's authorization model still decides what's reachable, exactly as it does for every other SeyalRun login path.

See Troubleshooting for common module install issues.