--- title: "Configure the Zabbix data source | Grafana Plugins documentation" description: "Learn how to configure the Zabbix data source for Grafana, including authentication, trends, Direct DB Connection, and provisioning." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Configure the Zabbix data source This document explains how to configure the Zabbix data source in Grafana, including authentication, trends, Direct DB Connection, and provisioning. ## Before you begin Before configuring the data source, ensure you have: - **Grafana permissions:** Organization administrator role. - **Zabbix API URL:** The full URL to your Zabbix API endpoint, including the `api_jsonrpc.php` path (for example, `http://zabbix.example.com/api_jsonrpc.php`). - **Zabbix credentials:** A username and password for a Zabbix user, or an API token. Verify the user has permissions to access the host groups and hosts you want to query in Grafana. ## Install and enable the Zabbix plugin Zabbix is an app plugin, so you must install it and then enable it before the data source becomes available. Enabling the plugin is a separate step from installation. 1. Click **Administration** > **Plugins and data** > **Plugins** in the left-side menu. 2. Type `Zabbix` in the search bar and select the **Zabbix** plugin. 3. If the plugin isn’t already installed, click **Install**. For other installation methods, refer to [Install Grafana plugins](/docs/grafana/latest/administration/plugin-management/). 4. On the plugin page, click **Enable**. The data source isn’t available to add until you enable the plugin. > Note > > In Grafana Cloud, the Zabbix plugin is installed and enabled for you after you add it from the plugin catalog. ## Add the data source After you enable the plugin, add the data source: 1. Click **Connections** in the left-side menu. 2. Click **Add new connection**. 3. Type `Zabbix` in the search bar. 4. Select **Zabbix**. 5. Click **Add new data source**. ## Configure connection settings Expand table | Setting | Description | |-------------|----------------------------------------------------------------------------------------------------------------------------------| | **Name** | The display name for this data source instance. | | **Default** | Toggle to make this the default data source for new panels. | | **URL** | The full URL of your Zabbix API endpoint, including `api_jsonrpc.php`. For example: `http://zabbix.example.com/api_jsonrpc.php`. | ## Configure authentication The Zabbix data source supports two authentication methods. Select the method in the **Auth type** drop-down under the **Zabbix Connection** section. > Note > > For Zabbix 7.0 and later, the plugin sends the authentication token (both session tokens and API tokens) in the `Authorization` HTTP header, as Zabbix requires. If you run Zabbix 7.0 behind a reverse proxy that uses HTTP basic authentication, the plugin keeps the token in the request body instead. Zabbix 7.2 and later don’t support HTTP basic authentication for API requests. Keep the plugin up to date so it uses the correct method for your Zabbix version. ### User and password Use a Zabbix user account to authenticate with the API. Expand table | Setting | Description | |--------------|--------------------------------------------------| | **Username** | The Zabbix username. | | **Password** | The Zabbix password. Stored securely in Grafana. | ### API token Use a Zabbix API token to authenticate. API tokens are available in Zabbix 5.4 and later. Expand table | Setting | Description | |---------------|---------------------------------------------------| | **API Token** | The Zabbix API token. Stored securely in Grafana. | ## Configure per-user authentication Per-user authentication maps each Grafana user to a Zabbix user so that queries respect the role-based access control (RBAC) already configured in Zabbix. When enabled, the plugin authenticates to the Zabbix API as the matching Zabbix user instead of using the shared credentials configured in the **Auth type** section. Find these settings under **Additional settings** > **Other**. > Note > > You need Grafana Admin permissions to configure per-user authentication, because the plugin must list Grafana users to build the exclusion list. If you can’t list users, contact your Grafana administrator. Expand table | Setting | Description | |------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Enable per-user authentication** | Toggle to map Grafana users to Zabbix users. When enabled, the plugin authenticates each request as the matching Zabbix user. | | **User identity field** | The Grafana user field used to match a Zabbix user. Values: **Username** (default) or **Email**. | | **Exclude users from per-user authentication** | A list of Grafana users that always use the global Zabbix credentials configured under **Auth type** instead of their own Zabbix identity. Defaults to `admin`. | ## Configure trends Trends store aggregated historical data (average, minimum, and maximum per hour) and are recommended for displaying long time ranges. Enable trends to improve query performance when viewing data older than your history retention period. Find these settings under **Additional settings** > **Trends**. Expand table | Setting | Description | |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Enable Trends** | Toggle to enable querying trends data for long time ranges. | | **After** | Time after which trends are used instead of history. Set this to your history storage period. Default: `7d`. Valid time specifiers: `h` (hours), `d` (days), `M` (months). | | **Range** | Time range width after which trends are used instead of history. Set this between 4 and 7 days to prevent loading large amounts of history data. Default: `4d`. | ## Configure Zabbix API settings These settings control caching and connection behavior for the Zabbix API. Find them under **Additional settings** > **Zabbix API**. Expand table | Setting | Description | |---------------|-------------------------------------------------------------------| | **Cache TTL** | How long the plugin caches metric names in memory. Default: `1h`. | | **Timeout** | Zabbix API connection timeout in seconds. Default: `30`. | ### Query timeout Under **Additional settings** > **Query Options**, you can set the maximum execution time for database queries initiated by the plugin. Expand table | Setting | Description | |-------------------|-----------------------------------------------------------------------------------------------------------------------------------| | **Query Timeout** | Maximum execution time in seconds for database queries. Queries exceeding this limit are automatically terminated. Default: `60`. | ## Configure Direct DB Connection Direct DB Connection lets the plugin query history and trend data directly from the Zabbix database through an existing Grafana SQL or InfluxDB data source. This bypasses the Zabbix API for historical data, which is faster on wide time ranges and reduces the amount of data transferred. Find these settings under **Additional settings** > **Direct DB Connection**. Expand table | Setting | Description | |---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | **Enable Direct DB Connection** | Toggle to enable direct database queries for history data. | | **Data Source** | Select an existing MySQL, PostgreSQL, or InfluxDB data source configured in Grafana that points to your Zabbix database. | | **Retention Policy** | (InfluxDB only) The retention policy name for fetching long-term stored data. Leave blank if you use only the default retention policy. | ### Set up a database data source Before enabling Direct DB Connection, you need a MySQL, PostgreSQL, or InfluxDB data source in Grafana that connects to your Zabbix database. The plugin uses this data source to execute history and trend queries. To add a database data source: 1. Click **Connections** in the left-side menu. 2. Click **Add new connection**. 3. Select **MySQL**, **PostgreSQL**, or **InfluxDB**. 4. Configure the connection to your Zabbix database. The database name is typically `zabbix`. 5. Click **Save & test**. For detailed configuration, refer to the [MySQL](/docs/grafana/latest/datasources/mysql/), [PostgreSQL](/docs/grafana/latest/datasources/postgres/), or [InfluxDB](/docs/grafana/latest/datasources/influxdb/) data source documentation. ### Database security The plugin needs only read access to the `history`, `history_uint`, `trends`, and `trends_uint` tables. To minimize data exposure, grant read access to only those tables. All queries run from the Grafana server, so you can also restrict connections to the Grafana host. MySQL example: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql GRANT SELECT ON zabbix.history TO 'grafana'@'' IDENTIFIED BY ''; GRANT SELECT ON zabbix.history_uint TO 'grafana'@'' IDENTIFIED BY ''; GRANT SELECT ON zabbix.trends TO 'grafana'@'' IDENTIFIED BY ''; GRANT SELECT ON zabbix.trends_uint TO 'grafana'@'' IDENTIFIED BY ''; ``` If you also want to use this data source for other queries, you can grant `SELECT` privileges to the entire Zabbix database: SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql GRANT SELECT ON zabbix.* TO 'grafana'@'' IDENTIFIED BY ''; ``` ## Configure problem severity overrides Zabbix lets administrators rename severities and change their colors globally under **Administration** > **General** > **Trigger displaying options**. The Zabbix data source offers the same kind of global override for Grafana under **Additional settings** > **Problem severity**. It applies to every Problems panel that queries this data source, so you don’t have to change the **Colors** options of each panel. Expand table | Setting | Description | |-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Not classified** … **Disaster** | One row per Zabbix severity. Enter a name to override the displayed severity name, and pick a color to override the severity color. Leave the name empty and the color unchanged to keep the plugin defaults. Click the **×** next to the color to reset it to the default. | How the overrides interact with panel settings: - A Problems panel that still uses the default name or color for a severity displays the global value from the data source. - A Problems panel that has its own custom name or color for a severity keeps it. Dashboards saved with custom severity names or colors aren’t changed by the global overrides. - When global overrides are in effect for a panel, the **Colors** section of the panel options shows an information banner, and each affected severity row is marked with a globe icon that shows the global value. - A panel that mixes several Zabbix data sources takes the overrides from its queries in order. The first data source that defines a name or color for a severity wins for that field. ## Configure other settings These settings are under **Additional settings** > **Other**. Expand table | Setting | Description | |----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Disable acknowledges for read-only users** | Prevents non-editor users from acknowledging problems in Grafana. | | **Disable data alignment** | Disables automatic alignment of time series points to the start of their collection interval. Data alignment is required for stacked graphs to render correctly. You can also toggle this per query in the query options. | ## Verify the connection Click **Save & test** to verify the connection. A successful test displays the message “**Zabbix API version**” followed by the detected version number. If Direct DB Connection is enabled, the message also includes the database connector type. If the test fails, refer to the [troubleshooting guide](/docs/plugins/alexanderzobnin-zabbix-app/latest/troubleshooting/) for common connection issues and solutions. ## Connect through Private Data Source Connect If your Zabbix server isn’t directly reachable from Grafana, for example a Grafana Cloud stack connecting to a Zabbix server on a private network, you can use Private Data Source Connect (PDC). The Zabbix data source supports PDC through the Grafana secure SOCKS proxy. To use PDC: 1. Set up a PDC connection for your Grafana Cloud stack. Refer to [Private data source connect (PDC)](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/). 2. Edit the Zabbix data source and select your PDC connection in the **Private data source connect** settings. 3. Click **Save & test**. PDC requires Grafana 10.0 or later. In self-managed Grafana, an administrator must enable the secure SOCKS proxy before the setting appears. ## Provision the data source You can define and configure the Zabbix data source in YAML files as part of Grafana’s provisioning system. For more information about provisioning, refer to [Provision Grafana](/docs/grafana/latest/administration/provisioning/#data-sources). The following example provisions a Zabbix data source with Direct DB Connection using a MySQL database: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: Zabbix type: alexanderzobnin-zabbix-datasource url: http:///zabbix/api_jsonrpc.php jsonData: authType: userLogin username: trends: true trendsFrom: '7d' trendsRange: '4d' cacheTTL: '1h' dbConnectionEnable: true dbConnectionDatasourceName: dbConnectionRetentionPolicy: '' disableReadOnlyUsersAck: false disableDataAlignment: false # Optional: global severity name and color overrides for Problems panels severityOverrides: - priority: 4 name: Critical color: 'rgb(220, 40, 40)' - priority: 5 name: Outage secureJsonData: password: version: 1 editable: false - name: MySQL Zabbix type: mysql url: :3306 user: jsonData: database: zabbix secureJsonData: password: ``` ### Provisioning configuration options The following table lists all available `jsonData` and `secureJsonData` fields for the Zabbix data source: Expand table | Field | Type | Description | |-------------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `authType` | `jsonData` | Authentication method. Values: `userLogin` (default) or `token`. | | `username` | `jsonData` | Zabbix username (for `userLogin` authentication). | | `password` | `secureJsonData` | Zabbix password (for `userLogin` authentication). | | `apiToken` | `secureJsonData` | Zabbix API token (for `token` authentication). | | `trends` | `jsonData` | Enable trends. Default: `true`. | | `trendsFrom` | `jsonData` | Time after which trends are used. Default: `7d`. | | `trendsRange` | `jsonData` | Time range width for switching to trends. Default: `4d`. | | `cacheTTL` | `jsonData` | Cache lifetime for metric names. Default: `1h`. | | `timeout` | `jsonData` | Zabbix API connection timeout in seconds. Default: `30`. | | `queryTimeout` | `jsonData` | Maximum execution time for database queries in seconds. Default: `60`. | | `dbConnectionEnable` | `jsonData` | Enable Direct DB Connection. Default: `false`. | | `dbConnectionDatasourceUID` | `jsonData` | UID of the Grafana data source for the Zabbix database. Preferred over `dbConnectionDatasourceName`. | | `dbConnectionDatasourceName` | `jsonData` | Name of the Grafana data source for the Zabbix database. Resolved to a UID at runtime when `dbConnectionDatasourceUID` isn’t set. | | `dbConnectionRetentionPolicy` | `jsonData` | InfluxDB retention policy name for long-term data. | | `disableReadOnlyUsersAck` | `jsonData` | Disable acknowledges for read-only users. Default: `false`. | | `disableDataAlignment` | `jsonData` | Disable time series data alignment. Default: `false`. | | `perUserAuth` | `jsonData` | Enable per-user authentication. Default: `false`. | | `perUserAuthField` | `jsonData` | Grafana user field used to match a Zabbix user. Values: `username` (default) or `email`. | | `severityOverrides` | `jsonData` | Global severity name and color overrides for Problems panels. A list of objects with `priority` (0-5), and an optional `name` and `color`. Fields that are omitted keep the plugin defaults. | | `perUserAuthExcludeUsers` | `jsonData` | List of Grafana users that always use the global Zabbix credentials. Default: `["admin"]`. | | `enableSecureSocksProxy` | `jsonData` | Route the connection through the Grafana secure SOCKS proxy for Private Data Source Connect (PDC). Default: `false`. | For detailed MySQL and PostgreSQL provisioning options, refer to the [MySQL provisioning](/docs/grafana/latest/datasources/mysql/#provision-the-data-source) and [PostgreSQL provisioning](/docs/grafana/latest/datasources/postgres/#provision-the-data-source) documentation. ### Provision with Terraform You can provision the Zabbix data source using the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs). The following example creates a Zabbix data source with user and password authentication: hcl ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```hcl resource "grafana_data_source" "zabbix" { type = "alexanderzobnin-zabbix-datasource" name = "Zabbix" url = "http:///zabbix/api_jsonrpc.php" json_data_encoded = jsonencode({ username = "" trends = true trendsFrom = "7d" trendsRange = "4d" cacheTTL = "1h" dbConnectionEnable = false disableDataAlignment = false }) secure_json_data_encoded = jsonencode({ password = "" }) } ``` For more information about the Grafana Terraform provider, refer to the [Grafana provider documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source). ## Next steps - [Build queries with the Zabbix query editor](/docs/plugins/alexanderzobnin-zabbix-app/latest/query-editor/) - [Use template variables for dynamic dashboards](/docs/plugins/alexanderzobnin-zabbix-app/latest/template-variables/) - [Set up alerting rules](/docs/plugins/alexanderzobnin-zabbix-app/latest/alerting/) - [Troubleshoot the Zabbix data source](/docs/plugins/alexanderzobnin-zabbix-app/latest/troubleshooting/)